tokensaver-egress

Capture HTTPS traffic from your AI agents (Claude Code, Cursor, n8n, …) and send audits to the TokenSaver control plane.

You run a small proxy on your machine. Your tools talk to the proxy; the proxy talks to Anthropic / OpenAI / … and reports what happened to TokenSaver (Flux IA).

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

Install

pip install -U tokensaver-egress
tokensaver-egress setup    # interactive wizard (recommended)

Or open the menu with a bare tokensaver-egress in a terminal (TTY).

Requires Python ≥ 3.10 and a TokenSaver API key (ts_…) from platform.tokensaver.fr.

Easiest path: guided setup

tokensaver-egress setup

The wizard walks you through:

1. API key (TOKENSAVER_API_KEY)
2. Ingest URL (default: production TokenSaver)
3. MITM on/off + create the local CA if needed
4. Trust instructions (and optional macOS keychain trust)
5. Body capture on/off
6. Port (default 8888)
7. Claude Code skills (CCR / onboarding) if missing — no tokensaver-cli required
8. Saves ~/.tokensaver-egress/env + client-env.sh, then offers to start the proxy

In another terminal:

source ~/.tokensaver-egress/client-env.sh
claude   # or your agent

Next time you can run tokensaver-egress → Start proxy now, or:

source ~/.tokensaver-egress/env
tokensaver-egress serve

5-minute setup (manual MITM)

MITM mode can see model, tokens, and tool names. You must trust a local certificate once.

1. Configure TokenSaver

export TOKENSAVER_API_KEY=ts_your_key_here
export TOKENSAVER_INGEST_URL=https://api.tokensaver.fr/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 (system keychain), then tell Node (Claude Code) to use it:

# macOS — trust the CA (admin password)
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  "$HOME/.tokensaver-egress/ca/ca.crt"

# Every terminal where you run Claude Code / Node agents
export NODE_EXTRA_CA_CERTS="$HOME/.tokensaver-egress/ca/ca.crt"

3. Start the proxy

EGRESS_MITM_ENABLED=true tokensaver-egress serve --port 8888

Leave this terminal open. You should see something like listening on …8888.

4. Point your tools at the proxy

In another terminal:

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"

# Example: Claude Code
claude

5. Check Flux IA

Open platform.tokensaver.fr → Flux IA / egress flows. New calls should appear within seconds.

Everyday commands

If the port is busy:

✖ Cannot listen on 0.0.0.0:8888 (Address already in use).
  Try:  tokensaver-egress serve --port 8889

Stop whatever is on 8888 (often another egress), or pick a free port and update HTTPS_PROXY.

Claude Code skills (no CLI needed)

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

Installs ~/.claude/skills/tokensaver-router (same plugin as tokensaver-cli): CCR, onboarding, MCP helpers. Restart Claude Code after install.

After Ctrl+C — clear the proxy in client shells

Stopping egress does not unset env vars in other terminals. If pip / curl still try localhost:8888:

source ~/.tokensaver-egress/client-unproxy.sh
# or:
eval "$(tokensaver-egress unproxy --sh)"
# or:
unset HTTPS_PROXY HTTP_PROXY

Then retry your install.

Examples

A. Claude Code (full capture)

# Terminal A — proxy
export TOKENSAVER_API_KEY=ts_…
export TOKENSAVER_INGEST_URL=https://api.tokensaver.fr/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).

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=ts_…
export TOKENSAVER_INGEST_URL=https://api.tokensaver.fr/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=ts_…
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).

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, use transparent mode / NetworkPolicy (see runbook).
• Bodies are optional; auth headers are masked unless you opt into raw headers.

Related

Monorepo helpers (developers):

./scripts/start-egress.sh --mode mitm --capture-bodies
./scripts/stop-egress.sh

License

MIT © TokenSaver