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.0
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.0.tar.gz | 68.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tokensaver_egress-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 137.0 kB
Release files / tokensaver_egress-0.1.0.tar.gz
| Download URL | tokensaver_egress-0.1.0.tar.gz |
|---|---|
| Size | 68.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
52fbafabc7f8bddfa54c029ffe436957a7d64009d499a95a2c723f4b513e7cfc
|
|
BLAKE2b-256 checksum How to use checksums |
783d1e97332458a98e4c635f83fcf103e5ff8ea80b41d7aaaec365f3e8469d7c
|
| 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.0-py3-none-any.whl
| Download URL | tokensaver_egress-0.1.0-py3-none-any.whl |
|---|---|
| Size | 68.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc7ff8d96610543d27fdcf3e898cd134fbbcdd9554e03b4bd346114763b3d1eb
|
|
BLAKE2b-256 checksum How to use checksums |
feb1b40285d62f868e04d12f32b4172d09a24716747690ad49502b796421eaf1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
