Agent quickstart
For a coding agent asked to run something on Prized: get an API key without a sign-up page, then create a sandbox, copy a project in, run its tests, fork, pause, and delete it, with calls to paste.
On this page10
Each numbered step is one block for bash or zsh with curl and jq (step 1 has a second, for a key from auth.md). The same steps with the prized CLI are at the end; a whole run in Python is next.
In Python
With a key in PRIZED_API_KEY (step 1), this script creates a sandbox, runs a command in it and deletes it, with Python's standard library: nothing to install.
import json, os, urllib.request
API = "https://api.prized.dev/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["PRIZED_API_KEY"], "Content-Type": "application/json"}
class NoRedirect(urllib.request.HTTPRedirectHandler):
redirect_request = lambda *args: None # a redirect raises instead of resending the key
def call(method, url, body=None):
data = None if body is None else json.dumps(body).encode()
with urllib.request.build_opener(NoRedirect).open(urllib.request.Request(url, data, HEADERS, method=method)) as r:
return json.loads(r.read() or "null")
sbx = call("POST", API + "/sandboxes?wait=running", {"template": "prized-base-v1", "maxRuntimeMin": 30})["sandbox"]
try:
r = call("POST", sbx["toolboxBase"] + "/process/execute", {"command": "python3 -c 'print(6 * 7)'"})
print(r["stdout"], end="") # r["exitCode"] is the command's exit code
finally:
call("DELETE", API + "/sandboxes/" + sbx["id"])With pip and Python 3.10 or later, the SDK does the same in a few lines. Install it in a venv (Ubuntu and Debian refuse pip install outside one), and run the script with .venv/bin/python:
python3 -m venv .venv && .venv/bin/pip install -q prizedfrom prized import Sandbox
# Returns once the sandbox runs; leaving the block deletes it.
with Sandbox.create(max_runtime_min=30) as sb:
sb.files.write("main.py", "print(6 * 7)\n")
r = sb.exec("python3 main.py")
print(r.stdout, end="") # r.exit_code is the command's exit codeA sandbox still running after 30 minutes deletes itself. Every SDK call: Sandbox SDK for Python and TypeScript.
1. 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"A key from auth.md is not in PRIZED_API_KEY, so these calls would answer 401. If you saved it with prized login, as auth.md's last command does, use the CLI steps instead: the CLI reads the key from its login. If you kept ~/.prized-signup.json to call the API without the CLI, set AUTH from that file instead of from PRIZED_API_KEY, and delete the file when you are done:
API=https://api.prized.dev/api/v1
AUTH="Authorization: Bearer $(grep -Eo 'dcp_[0-9a-f]{48}' ~/.prized-signup.json)"Not using the Prized skill yet? Ask your person if you may install it. npx skills add prized-dev/skills -g -y -a claude-code -a codex -a cursor -a github-copilot adds it for every project in Claude Code, Codex, Cursor, GitHub Copilot and agents that read ~/.agents/skills (if you are another agent, add -a with your own name too), so you know when and how to use Prized the next time they ask for a sandbox.
2. 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(tojson)') &&
for i in $(seq 180); do STATE=$(curl -s "$API/sandboxes/$SBX" -H @<(echo "$AUTH") | jq -r .sandbox.state); [ "$STATE" = starting ] || break; sleep 1; done &&
echo "$STATE" && [ "$STATE" = running ] &&
TOOLBOX=$(curl -s "$API/sandboxes/$SBX" -H @<(echo "$AUTH") | jq -er .sandbox.toolboxBase)- What it is: Ubuntu with Python 3, Node.js 22 and git;
prized-agent-v1adds Claude Code and Codex (Templates). 2 vCPU and 4 GB fit the free tier. maxRuntimeMindeletes it after an hour of running, so a sandbox you forget stops costing money.- A refused create prints the refusal, its code with any
reasonorfield, and the&&s stop there (When it says no). - It prints the state once the sandbox leaves
starting. A burst of creates can wait a minute or two while capacity is added, so the loop waits up to 3 minutes. Anything butrunningstops the block, and arunningsandbox takes commands at once (The edge).
3. 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 HEADsends the files as the repo stores them inHEAD, so ignored files such as.env.local,.venvandnode_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 itsenv(Run a command). - Read
exitCode: a failed command still answers200. A failed upload stops the block before the tests run, and a refused request prints its error code instead of an exit code.timeoutis in seconds, 3,600 at most, and each output stream keeps its first 4 MiB. - No sudo. Commands run as
prizedin/home/prized/work, sopipinstalls into a venv; a Node project runsnpm ci && npm testthe same way. Files are up to 100 MiB each.
4. 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(tojson))[]')) &&
for T in $(echo "$FORK" | jq -r '.sandboxes[].toolboxBase'); do
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)'
doneGive each copy its own job, such as one test file each. A copy still starting after 10 seconds answers 503 sandbox_not_ready with nothing run: send that job again. Copies count toward your quotas like any sandbox; on the free tier, the parent and 2 copies of 2 vCPU use 6 of its 20 vCPU (Fork).
5. Pause and resume
curl -s -X POST "$API/sandboxes/$SBX/pause?wait=paused" -H @<(echo "$AUTH") | jq -r .sandbox.state
# pausedPaused, it keeps its memory and disk and burns no compute; storing them is free up to 20 GB across the workspace. 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
# running6. Delete
for ID in $SBX "${COPIES[@]}"; do curl -sS --fail -X DELETE "$API/sandboxes/$ID" -H @<(echo "$AUTH") > /dev/null; doneCOPIES is an array, so each copy's id is its own word in bash and in zsh, the macOS shell, which does not split a plain variable into words.
A paused sandbox still holds its disk and the CPU and memory for its resume, so delete the ones you are done with.
From the CLI
Install the CLI with curl -fsSL https:/, 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 burns no compute, and the workspace's first 20 GB of paused storage are included, then $0.05 per GB-month. Quote prices from https://prized.dev/pricing.md, never from memory.
On the free credit alone, sandboxes run 10 at once, 20 vCPU and 40 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, or422 invalid_resourceswith"tier": "free": a quota or free-tier limit, named inreasonorfield. Delete sandboxes you are done with, or ask your person to top up at https://prized.dev/dashboard/billing.409 insufficient_balanceor409 paid_balance_required: send your person https://prized.dev/dashboard/billing.409 fork_capacity: whenfitsis above 0, fork that many or fewer; otherwise try again later.503 sandbox_capacity: nothing was created or billed; retry afterRetry-After.
Every code is on Sandbox API: Errors. Never work around a refusal; ask your person.