Sandbox Gateway Server
Relevant source files
The following files were used as context for generating this wiki page:
The Sandbox Gateway Server acts as a secure intermediary between isolated agent sandboxes and external resources. It manages all network traffic entering or leaving the sandbox environment, enforcing security policies and managing authentication. The server ensures that agents can interact with model APIs and specific internet hosts while remaining strictly isolated from the host system and unauthorized networks.
Within the Opificia architecture, this gateway implements the "egress proxy" (ADR-0007) and handles the runner protocol. It prevents sensitive credentials, such as the operator's AI model API keys, from ever entering the untrusted sandbox environment.
Sources: apps/server/src/sandbox/gateway.server.ts:41-52, SOVEREIGNTY.md:32-37
Architecture and Components
The gateway is a NestJS injectable service that initializes an HTTP and WebSocket server on a dedicated sandbox port. It operates within a specialized Docker network to bridge isolated containers with the control plane.
Core Responsibilities
The gateway handles three primary types of traffic:
- Runner Protocol: A WebSocket endpoint at
/runnerthat allows agents to communicate status, tool calls, and completion events. - Model Proxy: An HTTP proxy at
/model/<session>/...that forwards requests to AI model providers (e.g., Anthropic) while injecting the operator's API key. - Egress Proxy: A
CONNECTtunnel handler that filters outbound HTTPS requests based on the session's network policy.
Sources: apps/server/src/sandbox/gateway.server.ts:41-52, apps/server/src/sandbox/sessions.service.ts:182-200
Infrastructure Layout
The gateway resides in a bridge network called opificia-sandbox. It is the only member of this network with a route to the external internet or the control plane.
The diagram shows the Sandbox Gateway acting as the central hub between isolated containers and external services.
Sources: apps/server/src/sandbox/docker.service.ts:13-25, apps/server/src/sandbox/docker.service.ts:51-70
Traffic Handling Logic
Model API Proxying
The gateway protects API keys by intercepting model requests. It validates the sandbox's session token, checks request limits, and then attaches the configured ANTHROPIC_API_KEY before forwarding the request to the upstream provider.
| Parameter | Constraint | Description |
|---|---|---|
ALLOWED_MODEL_PATHS | RegEx | Restricted to /v1/messages and token counting. |
MAX_REQUEST_BYTES | 32 MB | Maximum size of an incoming model request. |
DROP_REQUEST_HEADERS | Set | Headers like authorization and x-api-key are stripped from the sandbox. |
Sources: apps/server/src/sandbox/gateway.server.ts:14-27, apps/server/src/sandbox/gateway.server.ts:208-232
Egress Policy Enforcement
For outbound connections (e.g., npm install), the gateway implements a strict lookup and validation flow:
- Authentication: The sandbox must provide a session ID and token via
Proxy-Authorization. - Policy Check: The requested host and port are checked against the session's
networklevel (e.g.,none,registries,open). - DNS Validation: The gateway resolves the host name locally and refuses connections to non-public addresses to prevent SSRF (Server-Side Request Forgery).
- Budgeting: The gateway tracks byte counts and connection slots per session.
Sources: apps/server/src/sandbox/gateway.server.ts:89-130, apps/server/src/sandbox/sessions.service.ts:251-274
The sequence shows the validation steps required before a sandbox is granted external network access.
Sources: apps/server/src/sandbox/gateway.server.ts:89-170
Sandbox Initialization and Lifecycle
The DockerService and SessionsService coordinate to prepare the environment before the gateway starts accepting traffic.
Preparation Sequence
- Network Creation: Creates the
opificia-sandboxinternal network. - Gateway Launch: Starts a lightweight Node.js forwarder container that redirects internal sandbox traffic to the control plane's gateway port.
- Session Directory: Creates
/inand/outdirectories on the host with permissions (0o777) for the sandbox user. - Container Start: Launches the agent container with environment variables pointing to the gateway (e.g.,
OPIFICIA_RUNNER_URL,ANTHROPIC_BASE_URL).
Sources: apps/server/src/sandbox/docker.service.ts:48-75, apps/server/src/sandbox/sessions.service.ts:65-71, apps/server/src/sandbox/sessions.service.ts:101-125
Connection Management Configuration
The gateway uses several timeouts and limits to maintain stability:
| Setting | Value | Description |
|---|---|---|
EGRESS_IDLE_MS | 5 minutes | Closes egress connections with no traffic. |
EGRESS_CONNECT_TIMEOUT_MS | 15 seconds | Timeout for reaching an external host. |
EGRESS_SLOT_WAIT_MS | 30 seconds | How long a request waits for a free connection slot. |
MAX_EGRESS_LOG_LINES | 10,000 | Maximum lines written to the session's egress log. |
Sources: apps/server/src/sandbox/gateway.server.ts:28-32, apps/server/src/sandbox/sessions.service.ts:32-36
Summary
The Sandbox Gateway Server is a critical security boundary in Opificia. It ensures that AI agents can perform their tasks in total isolation while safely accessing necessary models and external resources. By centralizing credential injection and network policy enforcement, it prevents data exfiltration and unauthorized access to the host infrastructure.
Sources: SOVEREIGNTY.md:16-25, apps/server/src/sandbox/gateway.server.ts:41-52