tokensaver-egress
Client-side HTTPS egress capture proxy for the TokenSaver control plane (ACP-4).
Runs on the client (Claude Code, Cursor, n8n, custom agents). Captures outbound HTTP/HTTPS — including flows that protocol-aware SDKs never see — then ships metadata (and optionally bodies) to POST /api/v1/egress/ingest.
Install
pip install tokensaver-egress
Editable (monorepo):
pip install -e "packages/egress[dev]"
Quick start
export TOKENSAVER_API_KEY=ts_...
export TOKENSAVER_INGEST_URL=https://api.tokensaver.fr/api/v1/egress/ingest
# Optional MITM (model / tokens / tool names)
tokensaver-egress init-ca
# Trust ~/.tokensaver-egress/ca/ca.crt on the client OS (+ NODE_EXTRA_CA_CERTS for Node)
export EGRESS_MITM_ENABLED=true
tokensaver-egress serve --port 8888
Point any client 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 Code / Node
Equivalent module form: python -m tokensaver_egress serve --port 8888.
Modes
| Mode | How | Capture |
|---|---|---|
| Explicit (default) | HTTPS_PROXY → proxy |
host, bytes, latency; HTTP JSON when parseable |
| MITM | EGRESS_MITM_ENABLED=true + trusted CA |
model, tokens, MCP/A2A, optional bodies |
| Transparent | tokensaver-egress serve --transparent + scripts/tproxy-setup.sh (Linux) |
original dst + SNI, metadata |
Env (common)
| Variable | Role |
|---|---|
TOKENSAVER_API_KEY |
Ship audits + governance (authorize, compress, …) |
TOKENSAVER_INGEST_URL |
Default SaaS: https://api.tokensaver.fr/api/v1/egress/ingest |
EGRESS_MITM_ENABLED |
TLS terminate known LLM hosts |
EGRESS_CAPTURE_BODIES |
Persist request/response bodies (auth headers masked) |
EGRESS_ENFORCE_ENABLED |
Pre-flight catalogue deny (zero-trust) |
OTEL_EXPORTER_OTLP_ENDPOINT |
Optional OTLP traces (e.g. http://localhost:4318/v1/traces) |
Monorepo helpers
From the TokenSaver platform repo:
./scripts/start-egress.sh --mode mitm --capture-bodies
./scripts/stop-egress.sh
Docs: RUNBOOK-EGRESS-ACP-4 · SPEC-ACP-4
Security note
HTTPS_PROXY is convenience, not a hard boundary. Real anti-bypass needs network controls (TPROXY / NetworkPolicy). MITM requires trusting a local CA you generate — only do this on machines you control.
Related
tokensaver-cli— route Claude Code / Cursor through the control planetokensaver-sdk— Python SDK
License
MIT © TokenSaver
1 maintainer
Release files for tokensaver-egress 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tokensaver_egress-0.1.1.tar.gz | 69.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tokensaver_egress-0.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 139.4 kB
Release files / tokensaver_egress-0.1.1.tar.gz
| Download URL | tokensaver_egress-0.1.1.tar.gz |
|---|---|
| Size | 69.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
68ea435692691f524ccb491b28eeaa2693597b646e26fb1824ca7b16294ed0cb
|
|
BLAKE2b-256 checksum How to use checksums |
16403dd29fe5586cbb8036f56aa5a84651784ea58cdf3084dc1288954f2479b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / tokensaver_egress-0.1.1-py3-none-any.whl
| Download URL | tokensaver_egress-0.1.1-py3-none-any.whl |
|---|---|
| Size | 70.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cbd7395e49396ae0e2f483ba261dc9fccf9349da4ab3326d31be4a7a800995f8
|
|
BLAKE2b-256 checksum How to use checksums |
723fc991518267270fd0fb1f808a019fed02f4136c54bc31b354f328a851a562
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
