Sandbox API

What a sandbox is, and how its lifecycle works, is on Sandboxes. The routes for boxes and the workspace are on API reference.

Two hosts, one key

Read toolboxBase from the sandbox object rather than building it; it is the same for the sandbox's whole life.

export PRIZED_API_KEY=dcp_…
API=https://api.prized.dev/api/v1
AUTH="Authorization: Bearer $PRIZED_API_KEY"

Authentication

Send Authorization: Bearer dcp_… on every request, with an API key from Dashboard → Settings → API keys (API keys). Expiry, revocation, and rotation work as on the rest of the API (Authentication).

A key acts as the member who made it: an owner's or member's key sees every sandbox in the workspace, and a contractor's gets 404 not_found on every sandbox route. On the free credit alone, a workspace works within the free tier's limits.

Conventions

Templates

{
  "templates": [
    {
      "id": "prized-base-v1",
      "resources": {
        "defaults": {"vcpu": 4, "memoryMb": 8192, "diskGb": 10},
        "min": {"vcpu": 1, "memoryMb": 1024, "diskGb": 10},
        "max": {"vcpu": 8, "memoryMb": 16384, "diskGb": 100}
      },
      "durability": "ephemeral",
      "defaultMaxRuntimeMin": 1440
    }
  ]
}

What each template holds is on Sandboxes: Templates.

Create

POST /api/v1/sandboxes answers 201 {sandbox} with state: "starting"; read it until running.

curl -s -X POST "$API/sandboxes" -H "$AUTH" -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" -d '{"template":"prized-agent-v1","resources":{"vcpu":2,"memoryMb":4096},"envVars":{"ANTHROPIC_API_KEY":"sk-ant-…"},"labels":{"run":"pr-1874"},"autoPauseMin":10,"autoDeleteMin":60,"maxRuntimeMin":120}'

The sandbox object

{
  "sandbox": {
    "id": "sbx_3f9c0a1b2d4e5f60",
    "state": "running",
    "template": "prized-agent-v1",
    "resources": {"vcpu": 2, "memoryMb": 4096, "diskGb": 10},
    "durability": "ephemeral",
    "labels": {"run": "pr-1874"},
    "autoPauseMin": 10,
    "autoDeleteMin": 60,
    "expiresAt": "2026-10-14T19:02:11Z",
    "errorReason": null,
    "toolboxBase": "https://…/v1/sandbox/sbx_3f9c0a1b2d4e5f60",
    "createdAt": "2026-10-14T17:02:11Z",
    "lastActiveAt": "2026-10-14T17:05:40Z"
  }
}

Read

Lifecycle

Fork

count is 1 to 256; labels replaces the parent's on every child. The answer lists the children, each starting; poll each until running.

{
  "fork": {
    "id": "frk_9a1c44e0b7d2f318",
    "parentId": "sbx_3f9c0a1b2d4e5f60",
    "count": 2,
    "status": "active",
    "sandboxIds": ["sbx_51d0c2aa9e8b7f64", "sbx_c8e4f1b20a3d9e75"],
    "createdAt": "2026-10-14T17:06:02Z"
  },
  "sandboxes": [{"id": "sbx_51d0c2aa9e8b7f64", "state": "starting", "…": "…"}]
}

What a child inherits, and the limits, are on Sandboxes: Fork.

Resize

A paused sandbox only. resources names any of vcpu, memoryMb, diskGb, within the template's bounds; disk never shrinks. The sandbox shows resizing, then paused again; its next resume boots fresh from the resized disk, without the paused memory.

{
  "sandbox": {"id": "sbx_3f9c0a1b2d4e5f60", "state": "resizing", "…": "…"},
  "operation": {
    "id": "…",
    "status": "pending",
    "resources": {"vcpu": 4, "memoryMb": 8192, "diskGb": 20},
    "coldRestart": true,
    "pausedMemoryDiscarded": true,
    "createdAt": "2026-10-14T17:10:00Z",
    "completedAt": null
  }
}

Read the sandbox until it leaves resizing: paused with the new resources when the resize succeeded, paused with the old ones when it was turned down before it began, or error (with errorReason) when it failed partway, after which the sandbox cannot resume and should be deleted. To read the operation itself, send the resize with an Idempotency-Key and send the same request again: the replay answers 200 with the operation as it is now, its status moving through pending and applying to succeeded, failed (with failureReason), or cancelled.

The edge

Routes below are relative to the sandbox's toolboxBase, with the same bearer. They need a running sandbox: a paused one answers 409 sandbox_not_running, and nothing on the edge wakes it.

Run a command

curl -s -X POST "$TOOLBOX/process/execute" -H "$AUTH" -H "Content-Type: application/json" -d '{"command":"npm test","cwd":"/home/prized/work/app","env":{"CI":"1"},"timeout":600}'
# {"stdout":"…","stderr":"","exitCode":0,"durationMs":8124}

• How it runs. bash -c as the user prized, in cwd (absolute; /home/prized/work by default), with the create's envVars and then this request's env on top.
• The answer is the verdict. A command that fails still answers 200; read exitCode.
• timeout is in seconds, 300 by default and 3,600 at most. At the limit the command and everything it started are killed: exitCode: -1, timedOut: true.
• Output. Each stream keeps its first 4 MiB; the rest is dropped. For more, write to a file and download it.
• One run per request. An exec whose answer was lost is never retried for you, since it may already have run; retry it yourself only if the command is safe to run twice.

Files

curl -s -X POST "$TOOLBOX/files/upload?path=/home/prized/work/app.py" -H "$AUTH" --data-binary @app.py
curl -s "$TOOLBOX/files/download?path=/home/prized/work/out.json" -H "$AUTH" -o out.json

Paths are absolute and inside /home/prized; a path through a symlink is refused. An upload creates missing directories and replaces the file whole, never half-written. Downloads are regular files only; list or archive a directory with a command (tar czf /home/prized/out.tgz work) and download that. Each transfer is up to 100 MiB and 10 minutes.

Edge limits

48 concurrent requests and 60 a second (bursts of 120) per key, and 8 concurrent and 20 a second (bursts of 40) per sandbox; past either, 429 rate_limited with Retry-After. The request document of an exec is at most 1 MiB.

Errors

The control plane:

The edge:

Not yet