---
title: "Questions: Deployment and operations"
canonical_url: "https://tokenobserve.com/faq/deployment"
published: 2026-09-02
last_updated: 2026-10-15
---

# Questions: Deployment and operations

What it runs on, how long onboarding takes, backup and restore, upgrades and rollback, air-gapped installs, and why there is no high-availability topology.

Q: What does Token Observe need to run?
A: A customer-hosted Token Observe installation needs one Node.js 24 process, or the published container image, and one configured database (normally a single SQLite file in WAL mode) holding the entire persistent state. There is no second datastore, cache tier, object store or message broker, so backing up that one file backs up the durable state. Terminate TLS in front of it: Token Observe speaks plain HTTP behind your proxy and manages no certificates, and at rest the database is encrypted by whatever your volume or host provides rather than by the product. Your reverse proxy must not buffer responses, or server-sent event streaming breaks; it must preserve the Authorization and x-api-key headers, set the forwarded headers, and allow a read timeout longer than your longest expected model response. The reference Compose file publishes on loopback rather than every interface, deliberately: the dashboard, the API and an unauthenticated Prometheus endpoint carrying agent identifiers and month-to-date spend share that listener.
Cite: https://tokenobserve.com/faq/deployment#what-does-token-observe-need-to-run

Q: How long does it take to get one agent governed?
A: For customer hosting, the onboarding guide plans about an hour for a first governed agent in a persistent installation from the full source distribution. This is a walkthrough estimate, not a measured onboarding result. Roughly twenty minutes cover the mechanical steps: install, boot, run the quickstart, mint a key, change one base URL, watch the first trace appear. Allow time for two decisions with your team: who owns the agent and what it is for, then which policy you are ready to enforce. The recommended order is to start every policy in shadow mode so the first day produces findings instead of outages, then promote to enforce once you know the false-positive rate. The install reports its own configuration through a readiness endpoint computed from live state rather than a setup flag, so it goes red again the day someone rotates a provider credential out of the environment.
Cite: https://tokenobserve.com/faq/deployment#how-long-does-it-take-to-get-one-agent-governed

Q: Does Token Observe support high availability?
A: No. The cloud pilot runs one replica with a parent process supervising separate workspace children and has no availability SLA. A customer-hosted runtime supports exactly one active process on one node in this release, whichever store is configured, and there is no replica, no clustering and no vendor-operated uptime SLA. SQLite is single-writer by design at this scale; under sustained heavy write load the bottleneck is trace-event insertion rather than the governance decision, and two instances must never point at one SQLite file. PostgreSQL is implemented and exercised in CI against a dual-backend contract, but a passing CI run proves adapter compatibility, not a production deployment, multi-replica safety, point-in-time recovery or a timed restore; the onboarding technical-readiness check deliberately keeps reporting not ready while a database URL is set. Several controls are also process-local: the login throttle, connector token buckets, identity-provider transactions, provider circuit state and upstream MCP sessions. Multiplying processes would multiply the throttle allowance. Keep workloads whose outage would harm customers outside this release.
Cite: https://tokenobserve.com/faq/deployment#does-token-observe-support-high-availability

Q: How do we back up and restore?
A: For customer hosting, Token Observe’s persistent state is one runtime database file, so back it up like evidence rather than like a cache. The shipped command takes a consistent snapshot against a live database, then reopens the artifact, runs an integrity check, walks every audit row and keyed checkpoint, captures that artifact’s exact head, and fsyncs the file and its manifest before publishing them; copying a live WAL database instead produces a plausible stale one. Record the four values the backup prints (sequence, audit hash, file digest and snapshot-descriptor digest) somewhere this deployment does not control, because that external tuple is what a restore is checked against. A restore also needs the ordered audit key ring injected, not just the file. Two limits: this is full-snapshot recovery and not point-in-time recovery, and there is no scheduled backup job, retention enforcement or freshness alarm; the three-copy policy is yours to run and monitor.
Cite: https://tokenobserve.com/faq/deployment#how-do-we-back-up-and-restore

Q: How do upgrades and rollbacks work?
A: Token Observe’s migrations are additive and backward-compatible, so you deploy the new code first and contract in a later release, and /readyz reports unready until migrations have applied; use it as the gate so traffic never reaches a half-migrated process. An ordinary one-release rollback works while no effect-required tool pin has ever been activated. After activation it does not, because an older binary does not understand the effect state machine and could dispatch that tool without it. The documented emergency path is a drained maintenance window: quarantine every effect-required pin using its already-reviewed descriptor hash, verify the catalogue reports each one quarantined, stop every process, then deploy the older image, keeping the pins quarantined until the fleet is effect-aware again. Rolling back two releases is not tested. If you cannot complete and verify that ceremony, preserve the database and escalate instead.
Cite: https://tokenobserve.com/faq/deployment#how-do-upgrades-and-rollbacks-work

Q: How many agents and how much traffic can one deployment take?
A: Token Observe offers no capacity commitment for a single deployment, because no measurement on partner-shaped data supports one yet. The documented envelope is roughly five to fifty API-key agents owned by one team, one or two model providers and a bounded set of pinned MCP tools. What the process does have is an admission ceiling: in-flight requests default to 256, and beyond it new work receives 503 ACP_OVERLOADED with a Retry-After while health, readiness and metrics probes stay reachable. Storage grew at roughly 3.1 KB per completed request under the laboratory mix. That laboratory baseline is the only published performance figure and it travels with its own conditions in the latency answer rather than being restated here; two of the six caveats on it are about capacity specifically — the request mix was a narrow deterministic one rather than yours, and the run was not the release container — and the source document’s closing instruction is not to turn it into a concurrency limit or a throughput commitment until a partner-shaped test has passed against agreed error, latency, storage and recovery thresholds. The soak harness that would close that gap ships; its evidence does not. It runs only the compiled artefact on loopback against a fresh temporary database and the in-process mock provider, supplies all of its own settings so live configuration cannot leak into the child process, and has no deployment-URL option at all. Duration is mandatory and bounded from one minute to twenty-four hours; the request mix is deterministic at 60 per cent allowed model calls, 20 per cent policy blocks, 10 per cent approval journeys and 10 per cent authenticated reads; and the defaults fail the run below 95 per cent of planned journeys, above 1 per cent unexpected outcomes, 0.1 per cent unexpected refusals, 1,000 ms at the 95th percentile, 2,000 ms at the 99th, 256 MiB of memory growth, 32 KiB of database growth per attempt, or 2.5 times latency degradation. Missing samples, early exit and interruption all fail closed. The harness closes the automation gap and does not retroactively close the evidence gap, and no completed multi-hour result is asserted.
Cite: https://tokenobserve.com/faq/deployment#how-many-agents-and-how-much-traffic-can-one-deployment-take

Q: Can Token Observe run air-gapped?
A: Yes. The customer-hosted version of Token Observe runs air-gapped, and the licence grants that explicitly alongside your own data centres and cloud accounts. The delivered image runs fully offline: the dashboard bundles no CDN assets, and beyond the providers, tool servers, webhook receivers, identity provider and anchor sink you configured there are exactly two other outbound paths. One is an admin-invoked lookup of the public OpenRouter price catalogue, which sends no prompt, trace or identifier; air-gapped installs never call it and post prices in instead. The other is the two shipped vendor pull connectors (GitHub Copilot seat spend and Cisco Umbrella DNS and proxy activity), whose hosts are fixed on the connector definition rather than named by you, and which open no socket until the connector scheduler is enabled and the credentials are set; an air-gapped install supplies neither, so neither ever runs. Egress is allowlisted rather than merely configurable, so a network policy permitting outbound connections only to your model providers, your tool servers and your webhook receivers leaves the product fully functional — adding your identity provider and your anchor sink only if you enabled those. One caveat belongs beside that claim: running the delivered image air-gapped is a different thing from building it from source, which still needs access to the base image, the Debian archives and the npm registry.
Cite: https://tokenobserve.com/faq/deployment#can-token-observe-run-air-gapped