Connecting agents (planned)
Planned. Self-hosted deployment is not available yet. Connecting agents works the same way as on the hosted service; the difference is the address. Where a page here and the hosted pages differ, this one applies to a self-hosted install.
Agents, collectors and OpenTelemetry exporters send to your deployment's address, the one you set as LEDGER_PUBLIC_URL (<your-domain> below stands for it; it is on your domain, never provantix.tech). Nothing in the data path goes through Provantix.
1. Register an emitter
As an administrator, open Setup in your deployment and register an emitter, exactly as on the hosted service. You get an emitter id and a private key shown once; the setup page shows commands with your address already filled in. See Emitters and keys.
2. Point the Node SDK at your deployment
The SDK sends signed batches to the /v1/batches endpoint of the base URL you give it. Use your own address:
import { AgentEmitter } from '@provantix/agent-sdk';
const emitter = new AgentEmitter({
emitterId: 'emi_01m…',
tenantId: 'ten_org_01m…',
privateKeyPem: process.env.PRIVATE_KEY.replace(/\\n/g, '\n'),
spoolDir: '/var/spool/provantix', // keep batches on disk if the deployment is unreachable
});
await emitter.flushAndDrain('https://<your-domain>');
See Node.js SDK for the rest of the options. Put the address in your own configuration (an environment variable or a settings file) so it can change without a code release.
If the deployment uses a certificate from your own authority, the agent's Node process must trust it:
export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-root-ca.pem
3. Other ways in
- Direct HTTP:
POST https://<your-domain>/v1/batches. See Direct HTTP API and POST /v1/batches. Batches are signed with the emitter key and limited to 10 MB. - OpenTelemetry: send traces (not logs or metrics) as OTLP over HTTP/JSON to
https://<your-domain>/v1/traceswith the intake token as a bearer token. See OpenTelemetry exporter. - Connectors and collectors (Microsoft Entra ID and Microsoft 365): a collector running next to your systems signs and ships its own batches to the same address. See Connectors.
3a. Network paths
Open these, from the machines that run agents and collectors to the deployment, on 443:
| From | To | Why |
|---|---|---|
| agent hosts | your Provantix hostname | batches, traces |
| collector hosts | your Provantix hostname | connector batches |
| people's browsers | your Provantix hostname | the app |
If agents are in a network that cannot reach it directly, put a relay or gateway in that network that forwards to your hostname. Keep the spool on disk so a short outage delays evidence instead of losing it.
4. Check the connection
From an agent host:
curl -sS https://<your-domain>/health # {"ok":true,"mode":"saas"}
Send a test record, then in the app open Connectors or Investigate: the emitter's last batch time should move, and the record should appear. The emitter list shows when each emitter last shipped.
5. What agents see when the licence changes
| Licence | What an agent gets |
|---|---|
| active, or no answer yet | Batches are accepted. |
| lapsed or revoked | HTTP 402. The SDK keeps the batch queued and retries; nothing is dropped while the queue has room. |
| over the agents bought | Batches are accepted. Overage is billed, never refused. |
There is no queue limit imposed by Provantix. A self-hosted deployment has no volume restrictions, so the SDK and the collector queue on disk for as long as the deployment is unreachable or the licence is lapsed, limited only by the disk you give them. The SDK's on-disk queue has a 2 GiB safety default; for a self-hosted deployment turn it off (SDK 0.3.0 and later, published):
const emitter = new AgentEmitter({
emitterId: 'emi_01m…',
tenantId: 'ten_org_01m…',
privateKeyPem: process.env.PRIVATE_KEY.replace(/\\n/g, '\n'),
spoolDir: '/var/spool/provantix',
spoolMaxBytes: null, // no limit: the disk is the only limit
});
For the collector daemon, set spoolMaxBytes: null in its options. Put the spool on a volume with room for your longest outage, and watch its free space.
6. Proving what you collected, offline
Verification does not depend on the licence or on Provantix. Export from the app, then verify with the offline verifier, using your deployment's public keys (not Provantix's), which your deployment publishes at /.well-known/provantix-export-keys.json:
curl -sS https://<your-domain>/.well-known/provantix-export-keys.json
See How verification works. A command-line export that works without signing in is planned for the first release.