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",
      "build": "prized-base-v1-r2",
      "resources": {
        "defaults": {"vcpu": 4, "memoryMb": 8192, "diskGb": 10},
        "min": {"vcpu": 1, "memoryMb": 1024, "diskGb": 10},
        "max": {"vcpu": 32, "memoryMb": 131072, "diskGb": 128}
      },
      "durability": "ephemeral",
      "defaultMaxRuntimeMin": 1440
    }
  ]
}

id is the name a create passes. build is the image a new sandbox of that name starts from today; it changes when the name is republished with a fix (Sandboxes: Templates), and resources are that build's. What each template holds is on the same page.

Create

POST /api/v1/sandboxes answers 201 {sandbox} with state: "starting"; read it until running. With ?wait=running the answer comes once it is running instead (Waiting). A large sandbox (more than 16 vCPU or about 58 GB of memory) may stay starting for a minute or two, longer than the hold: its held create answers 201 still starting, and you read it until running.

curl -s -X POST "$API/sandboxes?wait=running" -H "$AUTH" -H "Content-Type: application/json" -H "Idempotency-Key: pr-1874-1" -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":60}'

The Idempotency-Key is yours to choose, one per sandbox: resend the create with the same key and body, and you get the first sandbox back instead of a second (Conventions).

The sandbox object

{
  "sandbox": {
    "id": "sbx_3f9c0a1b2d4e5f60",
    "state": "running",
    "template": "prized-agent-v1",
    "templateBuild": "prized-agent-v1-r2",
    "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

Waiting

Create and resume take ?wait=running, and pause ?wait=paused: the API holds the answer until the sandbox gets there, so there is nothing to poll.

curl -s -X POST "$API/sandboxes/sbx_3f9c0a1b2d4e5f60/resume?wait=running" -H "$AUTH"

• It got there. Resume and pause answer 200, create 201, with the sandbox in its new state.
• It did not get there in time. The answer is the one without wait (202, or 201 for a create), with the sandbox as it is by then, still starting or pausing: read it until it settles, as without wait. A create that boots from scratch can outlast the hold.
• It failed. The hold ends at once, with the sandbox in error or on its way there; the status is the one without wait.
• It went another way. The hold also ends at once when the sandbox stops heading for that state: deleted (deleting, or gone, which answers as the request was accepted), or asked the other way by a later pause or resume (pausing or starting, or still running or paused if it had not moved yet). The status is the one without wait.
• A pause sent while the sandbox is still starting holds through the boot: it shows starting, then pausing, and answers 200 once it is paused (or as without wait at the bound).
• A change that reverses one in flight waits for the box, not the request: resume a sandbox that is still pausing and it shows starting until the pause has landed and it runs again; pause one still resuming and it shows pausing until it is paused. 200 comes only once it is really there.

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 run on a running sandbox, and wake one that is not:

• Paused or pausing: the request resumes it, as POST /resume would, then waits for running and runs. The resume is billed and counted as activity like any other, and a refused one answers with the resume's own error (409 insufficient_balance, 409 paid_balance_required, 429 sandbox_quota_exceeded, …), with nothing run.
• Starting or resuming: the request waits for running, then runs.
• The wait is up to 10 seconds, counted from when the edge, having checked the key and looked the sandbox up, finds it not running. Requests with the same key that arrive during a wait share it, deadline included, so a later one waits only what is left of it. Past the deadline the answer is 503 sandbox_not_ready with Retry-After: 1; nothing ran, so retry.
• A waiting request counts toward the sandbox's edge limits as a running one does: past 8 at once, the rest answer 429 rate_limited.
• Resizing: a request answers 409 sandbox_not_running at once and wakes nothing. Read the sandbox until it leaves resizing, then retry.
• Prized-Auto-Resume: false on a request turns waking off for it: a sandbox that is not running answers 409 sandbox_not_running, and nothing wakes. On a running sandbox the header changes nothing: the request runs and counts as activity, so it still holds off automatic pause. To watch a sandbox without keeping it up, read GET /api/v1/sandboxes/{id}, which is not activity.

Right after a sandbox reaches running, the first request can still answer 502 sandbox_unreachable (it may have run) while the edge's tunnel comes up. So when a create or resume returns, first send a harmless command, such as true, until it answers 200, as the SDK and CLI do; then send the real one.

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 in its process group are killed: exitCode: -1, timedOut: true. A process that left the group (setsid) runs on until it exits or the sandbox is deleted.
• 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. A request waiting for its sandbox to wake is one of them. The request document of an exec is at most 1 MiB.

Errors

The control plane:

The edge:

Not yet