Skip to content

TokenPak quickstart: your first measured receipt

This quickstart is for developers installing TokenPak for the first time. Install it, launch your agent through it, and get a measured receipt on the first request, then see your session's usage and runway as you work, without changing your code. The reference target is five minutes.

Install

pip install tokenpak

Requires Python 3.10+ (classifiers declare 3.10–3.13; on 3.13, the optional tree-sitter-languages wheel is unavailable and affected features gracefully degrade).

Verify your installation works:

tokenpak --help
tokenpak status

Configure and start

The interactive wizard detects optional provider API keys, picks a compression profile, and writes the configuration. New installs use ~/.tpk/config.yaml; an existing install keeps using its state-bearing ~/.tpk/ or legacy ~/.tokenpak/ home. Add --start to launch the proxy after configuration:

tokenpak setup --start

The wizard:

  1. Scans your environment for optional ANTHROPIC_API_KEY, OPENAI_API_KEY, and GOOGLE_API_KEY values. If none are present, setup continues normally for clients that already have their own credentials.
  2. Asks for the port and compression profile (minimal / balanced / aggressive). A default provider is requested only when direct provider keys were detected.
  3. Writes config, launches the proxy on 127.0.0.1:8766 because --start was supplied, and prints next steps.

To configure without starting anything, run tokenpak setup; start the proxy later with tokenpak start.

Point your client at the proxy

Run tokenpak integrate <client> to print the current setup steps. For clients that support managed configuration, tokenpak integrate <client> --apply can write the configuration; instruction-only targets continue with printed guidance. The manual environment-variable paths below remain valid:

Anthropic SDK and the anthropic Python client

export ANTHROPIC_BASE_URL=http://127.0.0.1:8766

Then use the SDK normally. TokenPak's proxy forwards your real ANTHROPIC_API_KEY upstream without storing it.

OpenAI SDK and compatible clients

export OPENAI_BASE_URL=http://127.0.0.1:8766/v1

Claude Code with TUI or CLI

Claude Code reads ANTHROPIC_BASE_URL from the environment the same as the SDK. Start Claude Code after setting the env var and it will route through TokenPak automatically.

With Claude Code, the default proxy preserves conversation turns, so a forwarded request can truthfully report zero tokens saved. Provider cache reuse is distinct from TokenPak context reduction; inspect attribution with tokenpak status --tip-cache. See the Savings reporting page for the full framing.

Codex CLI with OAuth

If Codex is already signed in, no OpenAI or Anthropic API key and no explicit model override are required:

tokenpak codex

TokenPak reuses Codex's existing OAuth request path and preserves the model selected by Codex. See Use TokenPak with Codex CLI for the temporary-session behavior when another Codex session is already running.

Other client tools

Cursor, Cline, Continue and Aider are compatibility targets, not yet independently verified. If a tool accepts an ANTHROPIC_BASE_URL or OPENAI_BASE_URL override in its config file or environment, you can point it at TokenPak and check tokenpak status for the request count. Consult the tool's own docs for the exact setting, and see the Cursor, Cline, Continue and Aider guides.

Direct Python with the SDK

import anthropic

client = anthropic.Anthropic(
    base_url="http://127.0.0.1:8766",
    api_key="your-anthropic-key"
)

Verify it works

tokenpak status

You should see the proxy up, the request count climbing, and per-session token metrics.

Check health:

curl http://127.0.0.1:8766/health

The expected response includes {"status": "ok", "version": "1.30.1"}.

See your usage and savings

After a handful of real requests through the proxy:

tokenpak savings
tokenpak cost --week

The local web dashboard at http://127.0.0.1:8766/dashboard visualizes cost and savings over time (also reachable via tokenpak dashboard).

How much to expect

TokenPak reports what it measured on your own traffic. It does not promise a savings figure, because the result depends on your integration path.

  • Default proxy path: the default proxy preserves conversation turns, so a forwarded request can truthfully report zero tokens saved. That result verifies routing and accounting without claiming savings that did not occur.
  • Explicit context tools: compression operations that you invoke explicitly can reduce eligible content. Measure the effect on your own traffic with tokenpak savings.
  • Provider cache: Provider cache reuse is distinct from TokenPak context reduction; inspect attribution with tokenpak status --tip-cache.

If you're evaluating TokenPak, start with a real session in Claude Code or Codex, read the receipt and tokenpak status, and then try explicit context tools on your own workload.

Keep it running

To keep the proxy available between sessions, use TokenPak's managed background process. Both tokenpak setup --start and tokenpak start launch it detached:

tokenpak start

Stop the process through the same lifecycle manager:

tokenpak stop

Network access: LAN exposure

If you intentionally expose the proxy to other machines on your LAN, opt in to a non-loopback bind and set a proxy auth token:

export TOKENPAK_BIND_ADDRESS=0.0.0.0
export TOKENPAK_PROXY_AUTH_TOKEN="$(openssl rand -hex 32)"
tokenpak start

Non-localhost clients must then include Authorization: Bearer <TOKENPAK_PROXY_AUTH_TOKEN> on every request. A remote request is rejected with 403 if the server has no proxy auth token configured, or 401 if the Bearer credential is missing or wrong. Localhost is always allowed. The proxy credential is stripped before forwarding; supply any direct provider credential separately, such as with x-api-key.

Next steps

  • Tune compression — tokenpak recipe --help for custom compression recipes.
  • Monitor savings — dashboard at http://127.0.0.1:8766/dashboard.
  • Spend Guard — tokenpak budget --help to configure rolling per-agent and per-fleet caps. The pre-send circuit breaker blocks runaway requests before they hit the provider.

Troubleshooting

"Connection refused" on http://127.0.0.1:8766

  • Verify the proxy is running: tokenpak status.
  • Check port 8766 isn't in use: lsof -i :8766.
  • Re-run tokenpak start (or the wizard via tokenpak setup --start).

"API key invalid" errors

  • Ensure your provider key is set: echo $ANTHROPIC_API_KEY.
  • TokenPak is transparent — your API key must be valid upstream.

Savings show zero after a few requests

  • Zero is a correct result for a forwarded request: the default proxy preserves conversation turns (see Savings reporting).
  • Check tokenpak status — it should show request count + token metrics.
  • Provider cache reuse is distinct from TokenPak context reduction; inspect attribution with tokenpak status --tip-cache.

Wizard prints "No API keys detected"

  • This is informational. Continue without a key when your client already has its own authenticated session, such as Codex OAuth. For direct provider API traffic, set only the relevant ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY and rerun setup.