Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Proxy

The reverse proxy lets you reach services running inside a sandbox from outside. It supports HTTP requests, SSE streams, and WebSocket connections.

Endpoints

  • ANY /proxy forwards to / inside the sandbox
  • ANY /proxy/{path} forwards to /{path} inside the sandbox
  • Header-routed requests on otherwise unmatched paths forward the original path unchanged. This lets clients use the same base URL for API and sandbox data traffic when they send routing headers.
  • When sandbox proxy domains are configured, host-based URLs shaped like {port}-{sandboxID}.{domain} forward the original path without routing headers.

Query strings are forwarded unchanged.

Required Headers

Each proxied request must identify the target sandbox and port:

HeaderDescription
x-agentenv-sandbox-idSandbox UUID to route to
x-agentenv-target-portPort of the service inside the sandbox

E2B-compatible aliases are also accepted:

HeaderAlias for
e2b-sandbox-idx-agentenv-sandbox-id
e2b-sandbox-portx-agentenv-target-port

These routing headers are stripped before the request is forwarded to the sandbox.

Host-based proxy requests derive both values from Host, for example http://8080-<sandbox-uuid>.sandbox.example.com/health targets port 8080. The configured domain must route to the AgentENV server in single-node mode or to the gateway in multi-node mode. Host-based proxy traffic is always treated as data-plane traffic; lifecycle and other control-plane APIs should use the base API host.