Documentation

Three steps from an empty console to team-level spend and usage.

For more than a machine or two, no one wants to approve each one in a browser. Make one key and reuse it everywhere.

In the console, open Connections, create an enrollment key, and turn on Reusable so the same key works on every machine. Then run this on each one: it installs, links, and starts the collector, with nothing to approve:

Drop that command into however you set machines up: your device-management tool (Jamf, Intune), an Ansible playbook, or the image your CI builds from.

Two switches if you need them: TOKENBASE_NO_SERVICE=1 installs and links without starting it in the background (for images that run the collector themselves), and TOKENBASE_NO_ENROLL=1 installs only, so you can link it later with tokenbase login.

The installer is safe to run again. It checks the current state first and only does the work that is missing, so wrapping it in Ansible, Chef, or Puppet will not churn. Pass --check for a dry run that reports what would change without touching anything.

On a headless server, a per-user background service stops at logout and will not start at boot. After the install, register a boot-persistent system service instead:

Verify what you run. Before installing, the script checks the download's signature and checksum against a key built into the collector, and the macOS build is notarized by Apple. To serve the binaries from your own copy, which is useful on networks with no direct internet access, point TOKENBASE_INSTALL_BASE at an internal mirror.

Keep the key out of logs. Rather than putting the enrollment key in the command, set TOKENBASE_AUTH_KEY_FILE to a path your secret manager mounts. The key is read from the file, so it never appears on a command line, in shell history, or in your tooling's logs:

Rotate and revoke. Keys expire automatically (30 days by default; set a longer window when you create one). Once a rollout is done, rotate a key in Connections to mint a replacement and retire the old secret, or revoke it outright. A reusable key is a standing credential, so treat it like one. Behind a proxy, the installer follows the usual HTTPS_PROXY setting.

What leaves the machine. Metadata only by default: token counts, models, hashed paths, and the machine name your device reports at enrollment, never your source or message text. Run tokenbase preview on a machine to see the exact bytes before anything is sent.

A signed, device-scoped binary tails the local session logs your AI coding agents already write: read-only, incremental, checkpointed by offset. It enrolls as a device with its own scoped credential and never depends on a live browser session. It is never in the model request path.

Metadata-only is the default. A local preview shows exactly what would be sent before anything leaves the machine.

There's one reader per agent, each versioned and tested against captured real session logs. Every reader reports how much of an agent's data it covers and flags anything it doesn't recognize; if one reader breaks, the rest keep working. v1 reads Claude Code and Codex CLI fully, Copilot CLI (real token counts and premium-request usage are read from the session log; cost is estimated, since Copilot bills by premium requests rather than tokens), and Cursor (in beta; its local storage was worked out by inspection, so its coverage is labeled rather than assumed).

Tier A is factual (straight from logs): tokens, models, session counts, tool calls, cache reuse, model mix, and estimated cost. Tier B is inferred (heuristics on local data): abandonment, retry loops, likely task type, and is always labeled as inferred, never presented as fact.

SaaS metadata-only (default), SaaS redacted-text (opt-in), VPC / on-prem, and local-only pilot. In zero-egress modes raw transcripts never leave the device and analysis runs against a local or VPC model.