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,
    "contain_custom_python": false,
    "strict_daemon_loopback": false
  },
  "profile": "safe",
  "contain_custom_python": false,
  "contain_custom_python_env_locked": false,
  "strict_daemon_loopback": false,
  "strict_daemon_loopback_env_locked": false
}

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.

config.contain_custom_python is the persisted setting (PUT it to toggle whether installed custom_python tools run contained under Safe/Strict vs. blocked). The top-level contain_custom_python is the effective value — the SNIPPBOT_CONTAIN_CUSTOM_PYTHON environment variable, when set, overrides and locks the persisted setting; contain_custom_python_env_locked is true then (the UI disables the toggle). strict_daemon_loopback follows the same pattern with SNIPPBOT_STRICT_DAEMON_LOOPBACK.

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
contain_custom_python	true/false	Run installed custom_python tools contained under Safe/Strict (vs. blocked). Env var overrides + locks it
strict_daemon_loopback	true/false	Under Strict, allow daemon-only loopback (Linux). Env var overrides + locks it

Note

Sandbox config uses PUT (not PATCH) for updates.

custom_python containment

Installed marketplace custom_python tools run in a per-package container under Safe/Strict when contain_custom_python is on (else they are blocked). Images are built at install time, so a package installed while the setting was off has no image; turning the setting on triggers an automatic backfill, and these endpoints expose its status + a manual retry.

Containment status

GET /api/sandbox/custom-python/status

{ "installed": 32, "needs_image": 23, "with_image": 20, "missing": ["@acme/pdf-tools"] }

needs_image counts installed tool packages that declare dependencies (a deps-less package uses the base image); with_image is how many have a built image; missing are those blocked until an image is built.

Rebuild missing images

POST /api/sandbox/custom-python/rebuild-images

{ "built": ["@acme/pdf-tools"], "failed": [], "skipped_no_runtime": false, "disabled": false }

Fail-soft (one package’s build error doesn’t abort the rest). disabled is true when containment is off; skipped_no_runtime when no Docker/Podman is available.

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
POST /api/sandbox/templates/{id}/use
DELETE /api/sandbox/templates/{id}

Manage container image templates. POST /{id}/use adopts a template as the active sandbox environment (image + captured settings).

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.