Sandboxes

Each sandbox is its own Firecracker microVM, with its own kernel. Sandboxes live in your workspace next to your boxes, draw on the same balance, and answer to the same API keys.

Sandboxes and boxes

• Use a box for the machine you work on: your repo, editor, synced folders, dev servers, and agents that run for days.
• Use a sandbox to run code you did not write or have not read (an agent's tool call, a user's snippet), one clean machine per request or test run, the same job fanned out across many copies, or anything that should be gone afterwards. Two guides walk through it: Run code from an AI agent in an isolated VM and Fork a running VM to run work in parallel.

Quickstart

A first sandbox in about a minute:

1. Open Sandboxes. New to Prized? It signs you up with the $30 free credit, no card, and opens the dashboard on Sandboxes, with no box tour.
2. Click Create API key there and export the key, as below. It reaches sandboxes only and expires after 90 days; the button shows until the workspace has a sandbox. A key from Dashboard → Settings → API keys with Full access, or Custom with Sandboxes: Write, works too.
3. Run one tab below. Each creates a sandbox from prized-base-v1, runs one command, and deletes it. The curl tab needs jq, and retries its command, which only prints a version, since a new sandbox can answer 409 or 502 for a moment after running (The edge). The CLI tab needs prized v0.21.0 or later: run curl -fsSL https://prized.dev/install.sh | sh, then the reload line it prints, in the terminal where you exported the key (Windows).

export PRIZED_API_KEY=dcp_…

On the free credit, sandboxes run within the free tier; once the workspace has paid in, the full quotas apply (Who can use sandboxes).

API=https://api.prized.dev/api/v1
AUTH="Authorization: Bearer $PRIZED_API_KEY"
CREATED=$(curl -s -X POST "$API/sandboxes" -H "$AUTH" -H "Content-Type: application/json" -d '{"template":"prized-base-v1"}')
SBX=$(echo "$CREATED" | jq -r '.sandbox.id // empty'); echo "${SBX:-$CREATED}"
# sbx_3f9c0a1b2d4e5f60, or the refusal, such as {"error":"insufficient_balance"}
for i in $(seq 60); do STATE=$(curl -s "$API/sandboxes/$SBX" -H "$AUTH" | jq -r .sandbox.state); [ "$STATE" = starting ] || break; sleep 1; done; echo "$STATE"
# running
TOOLBOX=$(curl -s "$API/sandboxes/$SBX" -H "$AUTH" | jq -r .sandbox.toolboxBase)
curl -s --retry 5 --retry-all-errors --fail-with-body -X POST "$TOOLBOX/process/execute" -H "$AUTH" -H "Content-Type: application/json" -d '{"command":"python3 --version"}'
# {"stdout":"Python 3.12.3\n","stderr":"","exitCode":0,"durationMs":41}
curl -s -X DELETE "$API/sandboxes/$SBX" -H "$AUTH" > /dev/null

A create on warm capacity is usually running in about five seconds; at busy moments it can wait in starting while capacity is added. Every field of a create is on Sandbox API: Create.

States

Pause and resume

A paused sandbox keeps its memory as well as its disk: on resume, every process carries on where it stopped. A single resume is usually back to running within two seconds. Pause and resume answer 202 at once; read the sandbox until it reaches paused or running, or send them with ?wait= and the answer comes once it has, if that is within about 8 seconds (the hold, plus up to half a second for its last look); past that it answers 202 as before, still pausing or starting, and you read it until it settles (Sandbox API: Waiting). The SDK waits that way for you, and so do the CLI's create and resume; prized sandbox pause answers at once unless you add --wait.

• Paused costs storage only. Disk and saved memory bill at the storage rate, no compute (Billing: Sandboxes).
• Paused still holds its quota. A paused sandbox keeps its CPU and memory reserved for its resume, so it counts against the workspace's running CPU and memory until you delete it (Limits: Sandboxes).
• Paused state lives on one machine. A paused sandbox's memory and disk stay on the machine it ran on. If that machine fails, or shortly after a pause the sandbox's process there stops unexpectedly, the sandbox goes to error and what it held is lost. Keep anything you need outside the sandbox.
• A command wakes it. A command, upload, or download sent to a paused sandbox resumes it, waits for it, and then runs; one sent while a sandbox is still starting or resuming waits the same way. The wait is up to 10 seconds, shared by the requests with the same key that arrive during it (The edge); past that the request answers 503 sandbox_not_ready with nothing run, and a retry picks it up. A sandbox that is resizing is not woken: its requests answer 409 sandbox_not_running until the resize ends. It is an ordinary resume: billed at the running rate from then on, counted as activity, and refused exactly as POST /resume would be, with the same error (409 insufficient_balance, 429 sandbox_quota_exceeded, and the rest).
• To never wake one, send the header Prized-Auto-Resume: false on the request: a paused sandbox then answers 409 sandbox_not_running and stays paused. The header only stops the wake: on a running sandbox the request runs and counts as activity like any other, so it holds off automatic pause. To watch a sandbox without keeping it running, read GET /api/v1/sandboxes/{id} instead, which is not activity.

Automatic pause and delete

Three create fields bound a sandbox's life, so a forgotten one stops costing money:

Exec and file requests count as activity, and a command keeps its sandbox awake for as long as it runs. POST /api/v1/sandboxes/{id}/refresh counts too, for an idle stretch with nothing to run. A resumed sandbox starts its idle count again.

Fork

curl -s -X POST "$API/sandboxes/$SBX/fork" -H "$AUTH" -H "Content-Type: application/json" -d '{"count":3}'

A fork turns one running sandbox into count live copies: each child has the parent's memory, disk, and every running process, as they were at the fork. The parent pauses briefly, usually under a second (up to a few seconds on its first fork), then keeps running. Children are ordinary sandboxes with their own ids, billed and counted like any other.

• The parent must be running. Fork it before you pause it.
• Copies start on the parent's machine. A request takes up to 256, but one machine holds at most 31 copies of a 1 vCPU sandbox, 15 of a 2 vCPU one, 7 of a 4 vCPU one (the default shape), and 3 of an 8 vCPU one; more memory or disk, or a busy machine, fits fewer. New sandboxes start, when they can, on a machine with room to fork them.
• A fork that does not fit makes nothing. It answers 409 fork_capacity with fits, how many copies fit now: fork that many or fewer (when fits is above 0), try again later, or start a new sandbox and fork that (it starts fresh). Keep the parent until the new one is running: while it holds its place, the new one cannot take that place on a full machine. The new sandbox and each copy count toward your quota (the free tier allows 4 at once): at the limit, delete sandboxes you no longer need and wait until they are gone (GET /api/v1/sandboxes/{id} answers 404, or prized sandbox ls no longer lists them; a sandbox still deleting counts), or raise it: on the free tier by topping up, otherwise by emailing team@prized.ac. Copy out what you need before you delete one, and never delete a parent while a copy forked from it is still starting: that copy fails.
• A sandbox too big to copy cannot fork at all. When its machine cannot hold even one copy beside it, a fork answers 409 parent_not_forkable with reason parent_too_big, the field that does not fit (vcpu, memoryMb, or diskGb), and a message. That starts past about 26 GB of memory, or about 105 GB for a sandbox created large. No retry or smaller count helps; fork a smaller sandbox.
• Quota counts every child. A fork that would pass a quota answers 429 sandbox_quota_exceeded with admitted, how many would have fit, and makes none.
• Children inherit the template, shape, environment variables, labels (unless the fork names its own), autoPauseMin, autoDeleteMin, and the parent's deletion time: a child never outlives its parent's maxRuntimeMin.

Resize

A paused sandbox can change its vCPU, memory, and disk within its template's bounds; disk only grows. The next resume boots fresh from the resized disk, so the paused memory and processes are discarded. A resize needs room in your quota for the larger of the old and new shape until it completes (Sandbox API: Resize).

Templates

• Shape. Both default to 4 vCPU, 8 GB of memory, and a 10 GB disk, and take 1 to 32 vCPU, 1 to 128 GB of memory, and 10 to 128 GB of disk (2 vCPU and 4 GB at most on the free tier). Up to 16 vCPU and about 58 GB of memory a sandbox is standard; past either it is large. GET /api/v1/sandbox-templates lists each template with its defaults and bounds.
• A template keeps its tools. Its tools are pinned; newer versions arrive as a new template name (prized-agent-v2), so a sandbox made today has the same tools as one made next month.
• A name can get a fixed build. A fix to the image that leaves the tools alone (boot speed, larger shapes) ships as a new build under the same name. New sandboxes start from the new build; a running or paused sandbox keeps the build it started from, and so do its forks. templateBuild on the sandbox, and build in GET /api/v1/sandbox-templates, name the build.
• Agents bring their own sign-in. Nothing is signed in on prized-agent-v1: pass the key the CLI reads, such as ANTHROPIC_API_KEY for Claude Code, in envVars.

Large sandboxes

A sandbox on prized-base-v1 or prized-agent-v1 goes up to 32 vCPU, 128 GB of memory, and 128 GB of disk. A large sandbox is one with more than 16 vCPU or about 58 GB of memory; anything smaller is standard.

• The first create can take a minute or two. It answers 201 with state: "starting" as usual and stays there until the sandbox is up; poll until running.
• The rate does not change. It is billed per second at the same rates as any shape: the vCPU and memory of 32 vCPU with 128 GB cost 32 times those of a 1 vCPU, 4 GB sandbox, and disk is billed on top by its size.
• It counts against the same quotas. The defaults hold one 32 vCPU, 128 GB sandbox; two need a higher running-memory quota (email team@prized.ac).
• A resize can be refused for room. A sandbox that cannot grow where it runs answers 409 resize_rejected with reason host_capacity; create a new one at the larger shape instead.
• Forks of a large sandbox are limited by its machine like any other (Fork).
• An older sandbox keeps its build's bounds. The larger shapes came with a new build of each template. A sandbox created before it (its templateBuild is prized-base-v1 or prized-agent-v1 itself), and its forks, resize within 8 vCPU, 32 GB of memory, and 100 GB of disk; create a new sandbox to go larger.

Inside a sandbox

Environment variables

envVars on the create are set for every command the sandbox runs, and for every command in its forks; a command's own env overrides them name by name. Up to 32, each name a shell identifier (letters, digits, and _, not starting with a digit) of up to 64 characters, each value up to 16 KiB.

They are stored encrypted, never returned by any route, and erased with the sandbox, so envVars is the place for a key the sandbox's code needs.

Who can use sandboxes

• Owners and members of a workspace, and API keys they made. Contractors do not see sandboxes; their requests answer 404 not_found.
• Any balance above zero. A workspace on the free credit alone uses sandboxes within the free tier; one that has paid in (a plan or a top-up) gets the full quotas. An empty balance cannot start one (409 insufficient_balance).
• API keys. A key with Full access reaches sandboxes. A Custom key needs Sandboxes: Read to list them and Sandboxes: Write for everything else, running commands and moving files included. The key an agent got at agent sign-in has Sandboxes: Write, and each sandbox it creates is a row on the audit log. A key limited to some boxes reaches no sandboxes (What a key can do).

Free tier

A workspace whose balance is only free credit (it has not paid in with a plan or a top-up) runs sandboxes within these limits:

• It spends the free credit. Sandboxes draw on it at the sandbox rates, like any compute; an empty balance answers 409 insufficient_balance.
• Past a limit the API answers as for any quota (429 sandbox_quota_exceeded with its reason, or 422 invalid_resources), with "tier": "free" in the body and the limit it hit as limit: sandboxes for sandbox_limit, vCPU for running_vcpu and vcpu, MB for running_memory and memoryMb, GB for retained_disk, minutes for max_runtime. For example, {"error": "sandbox_quota_exceeded", "reason": "running_memory", "tier": "free", "limit": 16384}. A top-up or a plan lifts the workspace to the full quotas.
• Sandboxes made while paying resume on the free tier only if they fit it: one bigger than 2 vCPU or 4 GB answers 422 invalid_resources (resize it down first), and one with more than an hour left before it is deleted answers 429 sandbox_quota_exceeded with reason max_runtime. Its lifetime is never shortened.
• A resize stays within 2 vCPU and 4 GB, and is accepted when the resized sandbox fits the free tier's totals, so shrinking one brings a workspace back inside them.
• The free credit's rules hold. One process at full CPU for 30 minutes pauses the workspace's boxes and sandboxes (Free credit).
• Switched off. If free-tier access is switched off for your workspace, a create, resume, or fork on the free credit alone answers 409 paid_balance_required until the workspace has paid in.

Dashboard

Sandboxes in the dashboard's sidebar lists every sandbox in the workspace with its template, shape, state, and what it costs an hour, against the workspace's quotas. Create, pause, resume, and delete from there; before the first sandbox, it offers a key in one click and the first request (Quickstart). A key made there stays at the top of the list after your first sandbox appears, until Done or you leave the page. With the CLI, skip the installer's sign-in and setup steps (they are for boxes): the key is all prized sandbox needs. A sandbox's own page shows its countdowns to auto-pause and deletion, live CPU and memory, its processes, and its events. The Templates tab lists the catalog, and API docs opens the Sandbox API reference.

Not yet