egress-gateway
Capability: substrate:sandbox
Harness: agnostic
A local host-allowlisting HTTP(S) forward proxy for the
Magpie framework. It is the egress-control chokepoint: framework
tools point HTTPS_PROXY/HTTP_PROXY at it, and the gateway rejects any
connection to a host that is not on its allowlist — before a socket is
opened. This is defence-in-depth for
RFC-AI-0003: even if a skill or a
prompt-injection tries to send private data to an arbitrary endpoint, the
destination is blocked.
The contract (what/why) lives in tool.md; this file is the
how-to.
Prerequisites
- Runtime: Python 3.11+ run via
uv(no system install needed). - Dependencies:
proxy.py(>=2.4,<3) — the forward-proxy runtime, resolved byuvfrom PyPI. - CLIs: None beyond the runtime.
- Credentials / auth: None.
- Network: Binds a loopback listen socket (default
127.0.0.1:8899) and makes unrestricted outbound by design — must run in a non-sandboxed context. Needs a writable$HOME(or aHOMEoverride) for runtime state under~/.proxy. The default allowlist covers general-purpose services (GitHub, Google APIs, PyPI, vulnerability registries), not ASF hosts. - Optional: the
devdependency group (pytest,ruff,mypy) for automated tests, and curl for manual verification.
Run it
Run the commands below from the repository root.
uv prepares the environment and installs the dependencies on first use.
# From a context that is NOT sandboxed — binding a listen socket and
# making unrestricted outbound is exactly this process's job.
uv run --project tools/egress-gateway egress-gateway # 127.0.0.1:8899
uv run --project tools/egress-gateway egress-gateway --port 9000
The supported mode is the default allowlisting forward proxy. Additional proxy.py arguments are passed through without filtering and must be supplied by a trusted operator. Extra services, plugins, and replacement handlers are outside the allowlist guarantee.
proxy.py keeps runtime state under $HOME/.proxy; if HOME is not writable
in your environment, point it somewhere writable for this process:
HOME=/tmp/egress-home uv run --project tools/egress-gateway egress-gateway
Point tools at it
export HTTPS_PROXY=http://127.0.0.1:8899
export HTTP_PROXY=http://127.0.0.1:8899
export NO_PROXY=localhost,127.0.0.1
Every framework tool that uses Python urllib (ponymail, whimsy, jira, …)
honours these automatically — no code change. Persist them per-machine in
.claude/settings.local.json’s env block (never committed — the gateway
is a local process).
Sandbox interaction: a sandboxed process can only reach the loopback
proxy if localhost/127.0.0.1 are in sandbox.network.allowedDomains
(see docs/setup/sandbox-troubleshooting.md
→ cannot bind to a localhost port). Adding them is loopback-only and does
not widen the internet egress surface — that is now the gateway’s job.
The allowlist
Defaults cover general-purpose services such as GitHub, Google APIs,
PyPI and vulnerability registries. ASF hosts are deliberately denied
by default, including issues.apache.org and *.apache.org.
Extend without editing code:
EGRESS_ALLOW_EXTRA="bedrock.example.com,.internal.corp" \
uv run --project tools/egress-gateway egress-gateway
Entries starting with . are treated as suffixes; everything else is an
exact host. Loopback (localhost, 127.0.0.1, ::1) is always allowed.
Security scope: EGRESS_ALLOW_EXTRA applies to the entire gateway
process, not just one project. The project-local ASF sandbox fragment
does not change this gateway’s allowlist.
ASF projects
A project with organization: ASF gets the ASF hosts from a gateway of its own, so no other project receives them.
Start it on a separate port:
EGRESS_ALLOW_EXTRA="lists.apache.org,dist.apache.org,repository.apache.org,downloads.apache.org,archive.apache.org,cveprocess.apache.org,issues.apache.org,whimsy.apache.org" \
uv run --project tools/egress-gateway egress-gateway --port 8900
Then point only that project at it, in its .claude/settings.local.json env block, as in Point tools at it.
The first six hosts are the ones in tools/agent-isolation/claude-settings.asf.fragment.json.
issues.apache.org and whimsy.apache.org are for tools that run in containers; drop the ones the project does not use.
Test
Automated tests
The automated tests cover the allowlist policy and CLI startup.
uv run --directory tools/egress-gateway --group dev pytest
Manual verification
Start the gateway as shown above, then run these commands in another terminal with curl available. The examples use the default proxy address and allowlist. The allowed request requires network access to PyPI.
# Allowed destination: expect a final HTTP 200 response from PyPI.
curl --noproxy "" --proxy http://127.0.0.1:8899 --max-time 10 --head https://pypi.org/
# Denied destination: expect HTTP 403.
curl --noproxy "" --proxy http://127.0.0.1:8899 --max-time 5 --include http://example.com/
The denied request returns HTTP 403 with egress-gateway: host not on allowlist in the response body.
Caveat — host-level, not payload-level
The gateway tunnels HTTPS via CONNECT; it allow/denies by host, not by
URL path or body. There is no TLS interception, so it cannot inspect request
payloads. That is the right model for egress control without MITM. If you
need per-path or content-level filtering, that is a different (heavier) tool.