Code Sandbox

The code sandbox executes untrusted code in isolated workspaces. Public traffic goes through the gateway under /v1/sandbox/*; direct service paths are dev-only shortcuts.

Backends

Backend	Select with	Notes
Docker	SANDBOX_BACKEND=docker	Local worker containers managed through Docker. Default for development.
E2B	SANDBOX_BACKEND=e2b plus deploy/docker-compose.e2b.yml	Remote/self-hosted E2B control plane for stronger production isolation.

Gateway Paths

The gateway strips /v1/sandbox before forwarding to the sandbox service.

Gateway path	Service path	Purpose
POST /v1/sandbox/execute	/execute	Run Python code.
POST /v1/sandbox/bash	/bash	Run shell command.
POST /v1/sandbox/read	/read	Read text file with pagination.
POST /v1/sandbox/read_binary	/read_binary	Read binary file/artifact.
POST /v1/sandbox/write	/write	Write a file.
POST /v1/sandbox/grep	/grep	Search file contents.
POST /v1/sandbox/glob	/glob	Match file paths.
GET /v1/sandbox/sessions	/sessions	List sessions. Admin only.
DELETE /v1/sandbox/sessions/{tenant_id}/{session_id}	/sessions/{tenant_id}/{session_id}	Destroy session. Admin only.
POST /v1/sandbox/sessions/{tenant_id}/{session_id}/copy	same	Bulk-write files into a workspace.

Example:

curl http://localhost:8080/v1/sandbox/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(42)",
    "language": "python",
    "tenant_id": "default",
    "session_id": "s1"
  }'

Artifacts

/execute and /bash can produce artifacts such as plots, tables, reports, and binary files. Agent-runtime recognizes sandbox artifact metadata and streams artifact SSE events so the frontend can attach them to the corresponding tool card.

Docker Isolation

Docker sessions are keyed by tenant and session. A session gets its own container and workspace volume. Defaults include:

Setting	Default
Network	Disabled
Memory	512m
Idle cleanup	900 seconds
Max sessions	50
User	Non-root worker user

GPU passthrough is opt-in with SANDBOX_GPU_ENABLED=true. GPU network stays disabled unless SANDBOX_GPU_NETWORK_ENABLED=true.

Path Handling

Text read/write paths are validated against absolute paths, null bytes, and .. traversal. grep and glob currently construct shell commands around their path inputs, so treat their path handling as more limited than read/write validation until that code is hardened.

Health and Metrics

Path	Purpose
/healthz	Liveness.
/readyz	Readiness.
/metrics	Prometheus metrics when scraped directly inside the network.

Configuration

Variable	Purpose
SANDBOX_BACKEND	docker or e2b.
SANDBOX_WORKER_IMAGE	Docker worker image.
SANDBOX_IDLE_TIMEOUT	Idle cleanup in seconds.
SANDBOX_MEM_LIMIT	Docker memory limit.
SANDBOX_MAX_SESSIONS	Concurrent session ceiling.
SANDBOX_GPU_ENABLED	Enable GPU passthrough.
SANDBOX_GPU_NETWORK_ENABLED	Allow network in GPU containers.
E2B_API_KEY, E2B_DOMAIN, E2B_TEMPLATE	E2B backend settings.
E2B_ALLOW_INTERNET_ACCESS, E2B_SECURE_ACCESS	E2B network/security controls.