Agent quickstart

Each step is one block for bash or zsh with curl and jq. The same steps with the prized CLI are at the end.

11. Get a key

• Your person has a key: use it. They make one at https://prized.dev/dashboard/workspace/api-keys with Full access, or Custom with Sandboxes: Write.
• New to Prized: make their account and your key yourself with auth.md: one call with their email address, one with the 6-digit code Prized emails them. No sign-up page; the account starts on the free credit, with no card.

The key is a credential: keep it where your person says, and never print or commit it. The calls below read it from PRIZED_API_KEY and pass the header as -H @<(echo "$AUTH"), through a pipe, so the key stays off curl's command line, which other programs on the machine can read.

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

22. Create a sandbox

SBX=$(curl -s -X POST "$API/sandboxes?wait=running" -H @<(echo "$AUTH") -H "Content-Type: application/json" -d '{"template":"prized-base-v1","resources":{"vcpu":2,"memoryMb":4096},"maxRuntimeMin":60}' | jq -er '.sandbox.id // error(.error)') &&
TOOLBOX=$(curl -s "$API/sandboxes/$SBX" -H @<(echo "$AUTH") | jq -er .sandbox.toolboxBase) &&
curl -sS --retry 5 --retry-all-errors --fail -o /dev/null -X POST "$TOOLBOX/process/execute" -H @<(echo "$AUTH") -H "Content-Type: application/json" -d '{"command":"true"}'

• What it is: Ubuntu with Python 3, Node.js 22 and git; prized-agent-v1 adds Claude Code and Codex (Templates). 2 vCPU and 4 GB fit the free tier.
• maxRuntimeMin deletes it an hour after the create, so a sandbox you forget stops costing money.
• A refused create prints its error code and the &&s stop there (When it says no). The last line runs true until the sandbox takes commands, which can lag running by a moment.

33. Copy the project in and run its tests

git archive --format=tar.gz HEAD | curl -sS --fail-with-body -X POST "$TOOLBOX/files/upload?path=/home/prized/work/project.tgz" -H @<(echo "$AUTH") --data-binary @- &&
curl -s -X POST "$TOOLBOX/process/execute" -H @<(echo "$AUTH") -H "Content-Type: application/json" -d '{"command":"tar xzf project.tgz && python3 -m venv .venv && .venv/bin/pip install -q -e . pytest && .venv/bin/python -m pytest -q","timeout":900}' | jq -c '{exitCode: (.exitCode // error(.error)), stdout, stderr}'
# {"exitCode":0,"stdout":"..  [100%]\n2 passed in 0.01s\n","stderr":""}

• Only the last commit goes. git archive HEAD sends the files as the repo stores them in HEAD, so ignored files such as .env.local, .venv and node_modules, uncommitted edits, and submodules stay on your machine. Commit what the tests need first. Send nothing else your person has not asked for, and pass what a command needs in its env (Run a command).
• Read exitCode: a failed command still answers 200. A failed upload stops the block before the tests run, and a refused request prints its error code instead of an exit code. timeout is in seconds, 3,600 at most, and each output stream keeps its first 4 MiB.
• No sudo. Commands run as prized in /home/prized/work, so pip installs into a venv; a Node project runs npm ci && npm test the same way. Files are up to 100 MiB each.

44. Fork it

Each copy starts with the parent's files, memory and running processes, the venv included:

FORK=$(curl -s -X POST "$API/sandboxes/$SBX/fork" -H @<(echo "$AUTH") -H "Content-Type: application/json" -d '{"count":2}')
COPIES=$(echo "$FORK" | jq -er '(.fork.sandboxIds // error(.error)) | join(" ")') &&
for T in $(echo "$FORK" | jq -r '.sandboxes[].toolboxBase'); do
  curl -sS --retry 5 --retry-all-errors --fail -o /dev/null -X POST "$T/process/execute" -H @<(echo "$AUTH") -H "Content-Type: application/json" -d '{"command":"true"}'
  curl -s -X POST "$T/process/execute" -H @<(echo "$AUTH") -H "Content-Type: application/json" -d '{"command":".venv/bin/python -m pytest -q","timeout":900}' | jq '.exitCode // error(.error)'
done

Give each copy its own job, such as one test file each. Copies count toward your quotas like any sandbox; on the free tier, the parent and 2 copies of 2 vCPU use 6 of its 8 vCPU (Fork).

55. Pause and resume

curl -s -X POST "$API/sandboxes/$SBX/pause?wait=paused" -H @<(echo "$AUTH") | jq -r .sandbox.state
# paused

Paused, it keeps its memory and disk and bills only to store them. The next command or file request resumes it, or resume it yourself:

curl -s -X POST "$API/sandboxes/$SBX/resume?wait=running" -H @<(echo "$AUTH") | jq -r .sandbox.state
# running

66. Delete

for ID in $SBX $COPIES; do curl -sS --fail -X DELETE "$API/sandboxes/$ID" -H @<(echo "$AUTH") > /dev/null; done

A paused sandbox still counts toward the quotas, so delete the ones you are done with.

From the CLI

Install the CLI with curl -fsSL https://prized.dev/install.sh | sh, then run the reload line it prints in the same terminal. It reads PRIZED_API_KEY, or the login auth.md shows how to save:

ID=$(prized sandbox create --vcpu 2 --memory 4 --max-runtime 1h)
git archive --format=tar.gz HEAD | prized sandbox cp - $ID:project.tgz &&
prized sandbox exec $ID --timeout 15m -- "tar xzf project.tgz && python3 -m venv .venv && .venv/bin/pip install -q -e . pytest && .venv/bin/python -m pytest -q"
COPIES=$(prized sandbox fork $ID --count 2)
prized sandbox pause $ID --wait
prized sandbox rm $ID $COPIES

cp - reads the archive from standard input. exec exits with the command's code; exec and cp resume a paused sandbox on their own (CLI: Sandboxes).

What it costs

A running sandbox bills per second: $0.04 per vCPU-hour, $0.0125 per GB-hour of memory, and $0.0001 per GB-hour of disk, so the 2 vCPU, 4 GB sandbox above is $0.131 an hour. Paused, it bills only its disk and saved memory. Quote prices from https://prized.dev/pricing.md, never from memory.

On the free credit alone, sandboxes run 4 at once, 8 vCPU and 16 GB in total, each up to 2 vCPU, 4 GB and 60 minutes. A top-up or a plan lifts these limits (Free tier).

When it says no

• 403 verification_required: the key from auth.md is not verified yet; finish its step 2.
• 429 sandbox_quota_exceeded, or 422 invalid_resources with "tier": "free": a quota or free-tier limit, named in reason or field. Delete sandboxes you are done with, or ask your person to top up at https://prized.dev/dashboard/billing.
• 409 insufficient_balance or 409 paid_balance_required: send your person https://prized.dev/dashboard/billing.
• 409 fork_capacity: when fits is above 0, fork that many or fewer; otherwise try again later.
• 503 sandbox_capacity: nothing was created or billed; retry after Retry-After.

Every code is on Sandbox API: Errors. Never work around a refusal; ask your person.