Sandbox API

Base path: /api/sandbox

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

Configuration

Get sandbox config

GET /api/sandbox/config

Response:

{
  "mode": "selective",
  "scope_mode": "session",
  "workspace_access": "rw",
  "resource_limits": {
    "cpu_cores": 1.0,
    "memory_mb": 512,
    "disk_mb": 2048,
    "max_processes": 50,
    "timeout_seconds": 300
  },
  "network_policy": {
    "enabled": false,
    "allowed_domains": [],
    "blocked_domains": []
  }
}

Update sandbox config

PUT /api/sandbox/config

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

Config values:

Field	Options	Description
`mode`	`off`, `selective`, `all`	Sandboxing mode
`scope_mode`	`session`, `agent`, `shared`	Container persistence
`workspace_access`	`none`, `ro`, `rw`	Access to agent workspace

Status

Get sandbox status

GET /api/sandbox/status

{
  "docker_available": true,
  "docker_version": "25.0.4",
  "active_containers": 2,
  "total_executions_today": 247
}

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.

Resource limits

Default limits by permission tier:

Tier	CPU	Memory	Disk	Timeout	Network
Sandbox	0.25 cores	128 MB	512 MB	60s	None
Restricted	0.5 cores	256 MB	1 GB	120s	None
Standard	1.0 core	512 MB	2 GB	300s	Restricted
Elevated	2.0 cores	1 GB	5 GB	600s	Full
Unrestricted	4.0 cores	2 GB	10 GB	1800s	Full