Sandbox API

Base path: /api/sandbox

All endpoints require authentication. See API Overview for auth details.

Tip

For sandbox configuration, use the Settings > Sandbox page in the Snippbot UI.

Configuration

Get sandbox config

GET /api/sandbox/config

Response — the full config plus the derived profile (read-only):

{
  "config": {
    "mode": "selective",
    "scope": "session",
    "workspace_access": "ro",
    "network": { "enabled": true, "allowed_domains": [], "blocked_domains": [] },
    "resources": { "cpu_cores": 1.0, "memory_mb": 512, "disk_mb": 1024, "max_processes": 64, "timeout_seconds": 300 },
    "smart_sandbox_risk_threshold": 0.5,
    "block_when_no_runtime": false
  },
  "profile": "safe"
}

Note

profile (off / safe / strict / custom) is derived from {mode, scope, workspace_access, network.enabled} — it is not a stored or accepted config field. To switch profiles, PUT the corresponding field values.

Update sandbox config

PUT /api/sandbox/config

{
  "mode": "all",
  "network": {
    "enabled": true,
    "allowed_domains": ["api.github.com", "registry.npmjs.org"]
  }
}

Caution

PUT /sandbox/config is a full replace (the body is deserialized into a complete config; omitted fields revert to defaults) — send the whole config, not a patch. Note the key is network, not network_policy. Domain lists are stored but per-domain filtering is not yet enforced (only enabled is wired).

Config values:

Field	Options	Description
mode	off, selective, all	Off / Safe / Strict mapping
scope	session, agent, shared	Container persistence
workspace_access	none, ro, rw	Access to agent workspace
smart_sandbox_risk_threshold	0–1	Safe-mode risk cutoff (≥ ⇒ containerize)
block_when_no_runtime	true/false	Fail closed (block) instead of host fallback

Note

Sandbox config uses PUT (not PATCH) for updates.

Status

Get sandbox status

GET /api/sandbox/status

{
  "status": "ok",
  "mode": "selective",
  "scope": "session",
  "profile": "safe",
  "runtime": { "available": true, "type": "docker", "version": "25.0.4" },
  "active_containers": 2,
  "degraded": false,
  "platform": { "system": "Darwin", "os_fence_supported": true, "windows_needs_wsl2": false }
}

• runtime.available — whether a container runtime is reachable (with type/version).
• degraded — true when the profile is Safe/Strict but no runtime is available, so commands run unsandboxed (surfaced, never silent). The engine also emits a sandbox.degraded event.
• platform — OS and capability signals for the runtime-status banner (os_fence_supported, windows_needs_wsl2).

Container management

List active containers

GET /api/sandbox/containers

Response:

{
  "containers": [
    {
      "id": "container_abc123",
      "agent_id": "agent_123",
      "scope": "agent",
      "status": "running",
      "created_at": "2026-03-02T10:00:00Z",
      "cpu_percent": 5.2,
      "memory_mb": 256,
      "executions_count": 42
    }
  ]
}

Get container details

GET /api/sandbox/containers/{id}

Stop a container

POST /api/sandbox/containers/{id}/stop

Restart a container

POST /api/sandbox/containers/{id}/restart

Destroy a container

DELETE /api/sandbox/containers/{id}

Permanently removes the container and its data.

Cleanup containers

POST /api/sandbox/containers/cleanup

Removes idle or orphaned containers.

Snapshots

GET  /api/sandbox/containers/{id}/snapshots
POST /api/sandbox/containers/{id}/snapshots
POST /api/sandbox/containers/{id}/snapshots/{sid}/rollback
DELETE /api/sandbox/containers/{id}/snapshots/{sid}

Save and restore container state via snapshots.

Templates

GET  /api/sandbox/templates
POST /api/sandbox/templates
POST /api/sandbox/templates/{id}/build
POST /api/sandbox/templates/{id}/pull
DELETE /api/sandbox/templates/{id}

Manage container image templates.

Audit

GET  /api/sandbox/audit
GET  /api/sandbox/audit/summary
POST /api/sandbox/audit/cleanup
GET  /api/sandbox/audit/{id}/output

Query sandbox execution audit logs.

Pool

GET  /api/sandbox/pool
POST /api/sandbox/pool/drain

Manage the pre-warmed container pool.

GPU

GET /api/sandbox/gpu

List available GPU resources.

Note

Code execution within sandboxed containers is handled by the agent’s tool system, not by direct API calls. There are no POST /api/sandbox/execute or POST /api/sandbox/execute/file endpoints.

Resource limits

Default limits by permission tier:

Tier	CPU	Memory	Disk	Max procs	Timeout
Sandbox	0.5 cores	256 MB	256 MB	32	60s
Restricted	1.0 core	512 MB	512 MB	64	120s
Standard	2.0 cores	1 GB	2 GB	128	300s
Elevated	4.0 cores	4 GB	8 GB	256	600s
Unrestricted	unlimited	unlimited	unlimited	unlimited	1800s

Network access is a flat, per-config setting (on/off), not tied to these tiers.