Sandbox Isolation & Execution

Relevant source files

The following files were used as context for generating this wiki page:

• apps/server/src/sandbox/docker.service.ts
• apps/server/src/sandbox/sessions.service.ts
• apps/server/src/sandbox/gateway.server.ts
• apps/server/src/worker/effects.service.ts
• SOVEREIGNTY.md
• AGENTS.md

Sandbox Isolation & Execution provides a secure, restricted environment for AI agents to perform code changes, run tests, and execute tools. This system ensures that agent activities remain contained, preventing unauthorized access to the host system or the wider network while maintaining auditability of all actions.

The system relies on Docker containers to enforce resource limits and file system isolation. A dedicated gateway controls all network traffic, acting as the sole egress point for sandboxes. This architecture supports the project's Sovereignty Commitments by allowing fully self-hosted, air-gapped execution where data location and access are strictly controlled.
Sources: SOVEREIGNTY.md:16-30, apps/server/src/sandbox/docker.service.ts:91-118

Core Architecture

The sandbox infrastructure consists of three primary components: the DockerService, the SessionsService, and the SandboxGateway. These components work together to provision, manage, and secure agent execution environments.

Component Interaction

The following diagram illustrates the relationship between the control plane and the sandbox environment:

The control plane manages the lifecycle of sandbox containers and provides a secure proxy for external communication.
Sources: apps/server/src/sandbox/docker.service.ts:35-86, apps/server/src/sandbox/gateway.server.ts:51-87, apps/server/src/worker/effects.service.ts:80-120

Docker Isolation

The DockerService creates and manages Docker containers with high-security configurations to ensure isolation. Each sandbox is a member of an internal-only bridge network named opificia-sandbox.

Container Hardening

Sandboxes are configured with the following restrictions:

• Read-only Root FS: The root file system is immutable to prevent persistent changes.
• Capability Dropping: All Linux capabilities are dropped (CapDrop: ["ALL"]).
• No New Privileges: Prevents the container from gaining additional privileges via setuid or setgid binaries.
• Resource Limits: Strict limits are enforced, typically 4GB of memory and 2 CPUs.
• Volatile Storage: /work, /tmp, and /home/node are mounted as tmpfs with specific size limits.
• Input/Output Mounts: The repository is mounted as read-only at /in, while results are written to a host-mapped directory at /out.

Sources: apps/server/src/sandbox/docker.service.ts:91-118

Sandbox Specification

The SandboxSpec type defines the parameters for a new container:

Field	Type	Description
sessionId	string	Unique identifier for the sandbox session.
runId	string	ID of the associated run.
image	string	The Docker image used for the sandbox.
inDir	string	Host path for read-only input repository.
outDir	string	Host path for writeable output.
env	Record<string, string>	Environment variables, including proxy tokens.

Sources: apps/server/src/sandbox/docker.service.ts:26-33

Network & Egress Control

Network isolation is enforced through a combination of Docker network settings and a specialized SandboxGateway.

The Gateway Container

The DockerService prepares an internal network and starts a gateway container (opificia-gateway). This container runs a TCP forwarder that bridges the internal sandbox network to the host's sandbox port. It is the only container in the internal network with a route to the control plane.
Sources: apps/server/src/sandbox/docker.service.ts:35-86

Egress Policy Enforcement

The SandboxGateway handles three types of traffic:

1. Runner Protocol: A WebSocket connection at /runner for command and control.
2. Model API Proxy: Requests to /model/<session>/... are forwarded to the model provider (e.g., Anthropic). The gateway injects the operator's API key so it never enters the sandbox.
3. Egress Proxy: Secure CONNECT tunneling for external network access (e.g., package registries).

The gateway resolves hostnames and verifies they map to public IP addresses before allowing connections. It also enforces session-specific EgressBudget limits.
Sources: apps/server/src/sandbox/gateway.server.ts:114-190, apps/server/src/sandbox/sessions.service.ts:182-192

Session Management

The SessionsService manages the lifecycle of a sandbox session from creation to exit. It tracks active sessions and speaks the runner protocol via WebSockets.

Execution Lifecycle

1. Creation: SessionsService.create records a session in the database and generates a secret token.
2. Launch: SessionsService.launch sets up host directories, configures environment variables (including OPIFICIA_RUNNER_TOKEN and OPIFICIA_EGRESS_PROXY), and starts the container.
3. Connection: The sandbox must send a hello message via WebSocket within HELLO_TIMEOUT_MS (3 minutes).
4. Monitoring: The service watches for exit codes, saves logs, and removes the container upon completion or failure.
5. Reconciliation: On server restart, reconcile() stops any orphaned sandboxes and marks their sessions as failed.

Sources: apps/server/src/sandbox/sessions.service.ts:101-164, apps/server/src/sandbox/sessions.service.ts:219-232

Audit Logging

The system records two types of logs for every session:

• Container Logs: Standard output and error from the Docker container, demuxed to remove Docker headers.
• Egress Logs: Every network decision (allowed or refused) is written to egress.log in the session's data directory.

Sources: apps/server/src/sandbox/docker.service.ts:127-149, apps/server/src/sandbox/sessions.service.ts:198-216

Security Configuration

The gateway enforces strict limits on communication to prevent resource exhaustion and data exfiltration.

Constraint	Value	Description
MAX_REQUEST_BYTES	32 MB	Maximum size for a single model request.
EGRESS_IDLE_MS	5 Minutes	Idle timeout for egress proxy connections.
MAX_EGRESS_LOG_LINES	10,000	Limit on log entries to prevent disk fill attacks.
HELLO_TIMEOUT_MS	3 Minutes	Maximum time for a sandbox to connect after start.
PidsLimit	1024	Maximum number of processes in a sandbox.

Sources: apps/server/src/sandbox/gateway.server.ts:16-25, apps/server/src/sandbox/sessions.service.ts:25-35, apps/server/src/sandbox/docker.service.ts:115

Sandbox Isolation & Execution ensures that Opificia agents operate in a highly controlled "trust-but-verify" environment. By combining Docker-level hardware isolation with gateway-level network interception, the system provides the security necessary for autonomous code manipulation while strictly adhering to the project's self-hosting and data sovereignty requirements.