Search guides, workflows, and reference pages.

Docs/Tools

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 by uv from 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 a HOME override) for runtime state under ~/.proxy. The default allowlist covers general-purpose services (GitHub, Google APIs, PyPI, vulnerability registries), not ASF hosts.
  • Optional: the dev dependency 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.

Suggest a change