API Reference

Sandbox API

Create and manage isolated execution environments for agent runs.

The Sandbox API provisions short-lived, container-based environments where agent code runs in strict isolation. Each sandbox enforces filesystem, network, and resource boundaries defined at creation time. Sandboxes are destroyed automatically after a configurable timeout or immediately when you call the delete endpoint.

POST /api/sandbox/create

POST /api/sandbox/create

Provision a new sandbox instance. The sandbox is ready to accept code execution requests once its status is "ready". On Free plans, up to 3 concurrent sandboxes are allowed.

Request body

{
  "agent_id": "data-processor",
  "mode": "container",
  "config": {
    "image": "agentcop/agent-sandbox:latest",
    "filesystem": {
      "read_only": ["/workspace/data"],
      "read_write": ["/workspace/output"],
      "blocked": ["/etc", "/root"]
    },
    "network": {
      "allow": ["api.company.com"],
      "block_outbound": true
    },
    "resources": {
      "cpu": "0.5",
      "memory": "512m",
      "timeout": 30
    }
  }
}

Field	Type	Description
`agent_id`	string	Agent this sandbox is being created for
`mode`	string	`container` (default) or `wasm` for lightweight WebAssembly sandboxes
`config.image`	string	Container image to use. Must be an approved image.
`config.filesystem.read_only`	string[]	Paths mounted read-only inside the sandbox
`config.filesystem.read_write`	string[]	Paths mounted read-write
`config.filesystem.blocked`	string[]	Paths that are inaccessible
`config.resources.cpu`	string	CPU shares (e.g., `"0.5"` for half a core)
`config.resources.memory`	string	Memory limit (e.g., `"512m"`)
`config.resources.timeout`	integer	Auto-destroy after this many seconds (max: 3600)

Response

{
  "sandbox_id": "sbx_abc123",
  "status": "ready",
  "mode": "container",
  "created_at": "2026-04-06T14:23:11Z",
  "expires_at": "2026-04-06T14:53:11Z"
}

GET /api/sandbox/{sandbox_id}

GET /api/sandbox/{sandbox_id}

Get the current status of a sandbox. Possible status values: provisioning, ready, running, destroyed, error.

Poll this endpoint after creation if you need to wait for the sandbox to be ready before submitting a run, though in practice container mode sandboxes are usually ready within 1–2 seconds.

DELETE /api/sandbox/{sandbox_id}

DELETE /api/sandbox/{sandbox_id}

Immediately destroy a sandbox and release all associated resources. Any in-progress run is terminated. The sandbox record is retained for billing and audit purposes but transitions to status: "destroyed".

Sandboxes are also destroyed automatically when their configured timeout elapses.

Returns 204 No Content on success.

POST /api/sandbox/{sandbox_id}/run

POST /api/sandbox/{sandbox_id}/run

Execute agent code inside the specified sandbox. The run is synchronous up to the request timeout (default: 30 seconds). For longer-running agents, use async: true to receive a run ID and poll for completion.

Request body

{
  "code": "result = agent.run('analyze sales data')",
  "timeout": 30
}

Field	Type	Description
`code`	string	Python code to execute inside the sandbox
`timeout`	integer	Per-run timeout in seconds (overrides sandbox default, max: 600)
`async`	boolean	If true, return immediately with a run ID instead of waiting

Billing note: Sandbox resources are billed per-minute of execution. Always destroy sandboxes when done, or set appropriate timeout values to avoid unexpected charges.

← Permissions API Approvals API →