tokensaver-egress

  ████████╗ ██████╗ ██╗  ██╗███████╗███╗   ██╗███████╗ █████╗ ██╗   ██╗███████╗██████╗
  ╚══██╔══╝██╔═══██╗██║ ██╔╝██╔════╝████╗  ██║██╔════╝██╔══██╗██║   ██║██╔════╝██╔══██╗
     ██║   ██║   ██║█████╔╝ █████╗  ██╔██╗ ██║███████╗███████║██║   ██║█████╗  ██████╔╝
     ██║   ██║   ██║██╔═██╗ ██╔══╝  ██║╚██╗██║╚════██║██╔══██║╚██╗ ██╔╝██╔══╝  ██╔══██╗
     ██║   ╚██████╔╝██║  ██╗███████╗██║ ╚████║███████║██║  ██║ ╚████╔╝ ███████╗██║  ██║
     ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚══════╝╚═╝  ╚═╝

        ┌─────────────────────────────────────────────────────────────┐
        │  EGRESS  ·  capture  ·  MITM  ·  compress  ·  govern        │
        │  Claude Code · Cursor · n8n · agents · HTTPS proxy          │
        └─────────────────────────────────────────────────────────────┘

Capture HTTPS traffic from your AI agents (Claude Code, Cursor, n8n, …) and send audits to TokenSaver → Flux IA.

Same TOKENSAVER ASCII wordmark as the tokensaver CLI — shown when you run tokensaver-egress serve / setup (disable with TOKENSAVER_NO_BANNER=1).

  Your agent  ──HTTPS──►  tokensaver-egress  ──►  api.anthropic.com / …
                                │
                                └── audits ──►  api.tokensaver.cloud  →  Flux IA

Quick start

Once — install and configure:

pip install -U tokensaver-egress
tokensaver-egress setup

Option A — one shell (simplest)

tokensaver-egress claude          # Claude Code CLI
# or
tokensaver-egress vscode          # VS Code (Claude Code extension) — proxy stays up
# or
tokensaver-egress launch          # client chosen during setup

claude starts the proxy if needed, then launches Claude Code. When Claude exits, the auto-proxy stops (unless you used --keep-proxy).

vscode opens VS Code or Cursor (PATH, .app bundle, or open -a) and leaves the proxy running. Stop later with tokensaver-egress stop.

Option B — two shells (see proxy logs)

# Terminal 1 — egress (logs stay visible here)
tokensaver-egress serve

# Terminal 2 — Claude through that proxy
tokensaver-egress claude --no-start

That’s it. Open app.tokensaver.cloud → Flux IA to see traffic.

Requires Python ≥ 3.10. The wizard asks for a TokenSaver account or a tsv_… virtual key.

What setup configures

Interactive wizard (tokensaver-egress setup):

Config is written to ~/.tokensaver-egress/env (+ client-env.sh). Setup also persists proxy env in:

• ~/.claude/settings.json env (Claude Code CLI — skipped if TokenSaver route ANTHROPIC_BASE_URL is set)
• VS Code / Cursor claudeCode.environmentVariables (when you pick VS Code / both)
• optional guarded snippet in ~/.zshrc (loads client-env.sh only while the proxy port is listening)

Re-apply without the wizard: tokensaver-egress ide. Strip IDE snippets: tokensaver-egress unproxy --ide.

Log in (existing account): choose option 2 → SaaS/Local → email + password → a key labeled Egress CLI is created and saved. Prefer Paste if you already have a key. SSO-only orgs: paste after IdP login. Details: Account options.

Other ways to run

tokensaver-egress stop   # kills :8888 + clears Claude / VS Code / shell proxy env
# Other terminals that still exported HTTPS_PROXY:
eval "$(tokensaver-egress unproxy --sh)"

Account options (API key)

tokensaver-egress setup
→ Keep this key? n          # when replacing an old key
→ 2) Log in …
→ 1) TokenSaver SaaS
→ email + password
→ key saved in ~/.tokensaver-egress/env

Notes:

• Login creates a new API key each time (plan key quota). Prefer paste to reuse a key.
• Email must be verified to create keys via login.
• SSO-only orgs: use paste after IdP login — not email/password.
• TOKENSAVER_ENTERPRISE=1 / TOKENSAVER_ORG_HINT=<slug> hide create account.

Architecture (client only)

tokensaver-egress is a lightweight client-side HTTPS proxy. It does not embed TokenSaver business logic, databases, or admin console.

Default ingest: https://api.tokensaver.cloud/api/v1/egress/ingest.

How it works (principles)

1. Runs next to the agent, not in the cloud — laptop, CI, or pod. SaaS never terminates your LLM TLS for you.
2. Traffic still goes to the real provider — Anthropic / OpenAI remain the destination. Unset HTTPS_PROXY and tools talk to providers directly again.
3. Metadata first — bodies off by default (EGRESS_CAPTURE_BODIES to opt in). Auth headers masked when bodies are captured.
4. Visibility levels — explicit HTTPS_PROXY · MITM (local CA) · transparent (Linux, advanced).
5. SaaS decides policy — the proxy fetches effective settings for your key.
6. Streaming stays interactive — no “buffer everything then reply” for normal chat.
7. Fail soft by default — brief SaaS outages usually don’t block forward.
8. Your key is the trust boundary — without a valid TOKENSAVER_API_KEY, Flux IA stays empty.

Everyday commands

If the port is busy: tokensaver-egress serve --port 8889 (and update HTTPS_PROXY), or tokensaver-egress stop.

Claude Code skills

tokensaver-egress install-skills
# or: tokensaver-egress install-skills --force

Installs CCR / onboarding / MCP helpers. Restart Claude Code after install.

After Claude / Ctrl+C — clear proxy env

tokensaver-egress stop kills the process and strips persisted proxy env (Claude settings.json, VS Code, shell rc snippets, client-env.sh). Other interactive shells that already exported HTTPS_PROXY still need a local unset:

tokensaver-egress stop
# then restart Claude Code / reload the IDE window

5-minute setup (manual MITM)

MITM can see model, tokens, and tool names. Trust a local CA once.

1. Configure TokenSaver

export TOKENSAVER_API_KEY=tsv_your_virtual_key_here
export TOKENSAVER_INGEST_URL=https://api.tokensaver.cloud/api/v1/egress/ingest

2. Create the local CA (once)

tokensaver-egress init-ca
# Writes: ~/.tokensaver-egress/ca/ca.crt

Trust that CA on this Mac, then tell Node (Claude Code) to use it:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  "$HOME/.tokensaver-egress/ca/ca.crt"

export NODE_EXTRA_CA_CERTS="$HOME/.tokensaver-egress/ca/ca.crt"

3. Terminal 1 — start the proxy

EGRESS_MITM_ENABLED=true tokensaver-egress serve --port 8888

4. Terminal 2 — point tools at the proxy

export HTTPS_PROXY=http://127.0.0.1:8888
export HTTP_PROXY=http://127.0.0.1:8888
export NODE_EXTRA_CA_CERTS="$HOME/.tokensaver-egress/ca/ca.crt"
claude
# or: tokensaver-egress claude --no-start

5. Check Flux IA

app.tokensaver.cloud → Flux IA — new calls should appear within seconds.

Examples

A. Claude Code (full capture)

# Terminal A — proxy
export TOKENSAVER_API_KEY=tsv_…
export TOKENSAVER_INGEST_URL=https://api.tokensaver.cloud/api/v1/egress/ingest
EGRESS_MITM_ENABLED=true EGRESS_CAPTURE_BODIES=1 \
  tokensaver-egress serve --port 8888

# Terminal B — agent
export HTTPS_PROXY=http://127.0.0.1:8888
export HTTP_PROXY=http://127.0.0.1:8888
export NODE_EXTRA_CA_CERTS="$HOME/.tokensaver-egress/ca/ca.crt"
claude

EGRESS_CAPTURE_BODIES=1 stores request/response bodies in TokenSaver (auth headers are masked). Omit it if you only want metadata (host, latency, tokens).

A′. Audit-only (journalisation seule — TNF bisection)

Forward the client body unchanged to Anthropic (no cache / RAG / compression / PII / routing), while still ingesting audit rows. Use this for the « without TokenSaver transforms » leg of a thread_not_found bisection:

EGRESS_MITM_ENABLED=true EGRESS_CAPTURE_BODIES=1 EGRESS_AUDIT_ONLY=1 \
  tokensaver-egress serve --port 8888

(EGRESS_PIPELINE_MODE=audit is an alias.) Audit attrs include audit_only=true and pipeline_modules=["audit_only"].

B. One-shot curl through the proxy

# Proxy already running with MITM + CA trusted
export HTTPS_PROXY=http://127.0.0.1:8888
curl -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

C. Metadata only (no TLS decrypt)

No CA trust needed. You still see host / bytes / latency, not model tokens.

export TOKENSAVER_API_KEY=tsv_…
export TOKENSAVER_INGEST_URL=https://api.tokensaver.cloud/api/v1/egress/ingest
tokensaver-egress serve --port 8888

# Client
export HTTPS_PROXY=http://127.0.0.1:8888
export HTTP_PROXY=http://127.0.0.1:8888

D. Local TokenSaver backend (dev)

export TOKENSAVER_API_KEY=tsv_…
export TOKENSAVER_INGEST_URL=http://localhost:8000/api/v1/egress/ingest
EGRESS_MITM_ENABLED=true tokensaver-egress serve --port 8888

Modes (simple)

Most people want MITM + explicit proxy (sections above).

Mental model: explicit = “I opted this shell in”; MITM = “I also trust a local cert so TokenSaver can enrich the audit”; transparent = “the network forces traffic through the proxy” (ops / lock-down setups).

Transparent (Linux only):

sudo EGRESS_PORT=8888 ./scripts/tproxy-setup.sh up
tokensaver-egress serve --transparent --port 8888

Useful environment variables

Troubleshooting

Security

• Run MITM only on machines you control. The CA can decrypt traffic you route through the proxy.
• HTTPS_PROXY is easy to unset — it is not a hard security boundary. For lock-down, see k8s/networkpolicy.example.yaml / transparent mode.
• Bodies are optional; auth headers are masked unless you opt into raw headers.

Related

License

MIT © TokenSaver