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.3
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.3.tar.gz | 70.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tokensaver_egress-0.1.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 141.7 kB
Release files / tokensaver_egress-0.1.3.tar.gz
| Download URL | tokensaver_egress-0.1.3.tar.gz |
|---|---|
| Size | 70.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e49c05a4284efbd6caf36126d5cf0d32b74a56aee6635f18e52975dba020a524
|
|
BLAKE2b-256 checksum How to use checksums |
37d2ef23de990fc4b1df3a54e94ce1661b5d581bec68184740332d56f801939b
|
| 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.3-py3-none-any.whl
| Download URL | tokensaver_egress-0.1.3-py3-none-any.whl |
|---|---|
| Size | 71.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f203721911b211cbc5dc8bdf8201bba6b79d31e974b853460d8dd620cb5c0028
|
|
BLAKE2b-256 checksum How to use checksums |
2c636589df52951b1188b37b1dc7043c82915fc80c8af4e68ceab71fb351c64f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
