An agent often needs the internet to install dependencies. Ryph’s egress proxy permits selected hosts while keeping the allowlist outside repository control. It is a separate service from the model proxy and MCP gateway.
For what this means day to day, including how environment builds are confined, see Egress confinement.
Resolve the allowlist
The deployment chooses proxy or open mode. In proxy mode, its allowlist defines a ceiling made of registry bundles and additional hostnames. Environment variables seed that ceiling; a saved administrator allowlist takes precedence afterward.
An agent’s network policy can narrow the ceiling. It cannot introduce a bundle or host that the deployment does not permit. With no agent override, the run inherits the ceiling. Repository files cannot request additional egress.
The bundle catalogue expands familiar names into the hostnames they need. The catalogue holds npm, deno, pypi, cargo, debian, golang, github-releases, rustup, node-dist, mise and playwright, and every bundle is in the default ceiling. Extra hosts and wildcard subdomains can be allowed explicitly.
Freeze a signed claim
At launch, the orchestrator freezes the expanded host list into the run’s network scope and signs a token containing the run ID, expiry and hosts. The runner supplies proxy settings to setup steps and the harness.
The proxy verifies the token itself. It does not fetch the agent’s current blueprint or consult the orchestrator on each request. Editing a policy therefore affects future runs, not tokens already issued.
The egress token has no revocation list. Its default lifetime is 24 hours, configurable at deployment. Ending the run revokes its model, MCP and forge keys, but does not invalidate an already issued egress token.
Check destinations
The proxy accepts HTTP forwarding and HTTPS CONNECT on ports 80 and 443. It compares hostnames against the signed allowlist and checks the TLS ClientHello’s server name for HTTPS tunnels. It does not decrypt application traffic or inspect individual URL paths.
DNS resolution is also checked before dialing. By default, private, loopback, link-local and other blocked addresses are refused, including metadata destinations. An allowlisted name does not automatically authorize access back into the platform’s network.
Allowing a hostname is a broad grant: the run can communicate with that host, not just download one approved package. Package registries and GitHub release hosts should be selected with that scope in mind.
Prevent bypasses
The proxy can only enforce the requests that reach it. The sandbox network must prevent a run from dialing the internet directly.
| Backend | Network enforcement |
|---|---|
| Kubernetes | Supplied NetworkPolicy permits platform endpoints, DNS and the egress proxy, without general direct internet access. The cluster must enforce these policies. |
| Docker, confined | Each run joins an internal Docker network with no route out. It reaches Ryph and the egress proxy only through the run gate, a small relay container. Needs Docker Desktop, or Docker Engine 28 or later on Linux. Podman isn’t supported. |
| Docker, allowlisted | Ryph supplies proxy settings, but the container keeps a direct route. Setup steps follow the allowlist; a run’s own code can go around it. |
ryph setup offers confined wherever the engine supports it, and the Docker Compose deployments use it too.
RYPH_EGRESS=open explicitly disables the proxy-mode boundary. A hostname allowlist in configuration should never be read as proof of confinement without checking the backend’s route out.
The platform’s web search and fetch tools reach the internet from the web service, not from the run, so the egress allowlist does not limit them. Fetch reads public HTTPS pages only and returns them as untrusted text. Agents get these tools by default; an agent’s tool policy can remove them, and RYPH_WEB_TOOLS=off disables them for the deployment.
Follow the implementation
The policy and registry catalogue live in egress.ts. The proxy implementation handles token verification, host checks, DNS restrictions and forwarding. The network manifests provide the Kubernetes backstop.