Prized Python SDK: Sandboxes (beta)

A sandbox is a microVM your code creates, runs commands in, moves files in and out of, pauses for the price of its storage, forks into live copies, and deletes. This package is the Python client for the Prized Sandboxes API, with a sync Sandbox and an asyncio AsyncSandbox that share one surface.

Sandboxes are in beta. A workspace on free credit alone runs them on the free tier: up to 10 at once, each up to 2 vCPU and 4 GB of memory and 60 minutes of running. A top-up or a paid plan lifts the limits: a sandbox then runs up to 7 days at a stretch, and a paused one is kept until you delete it.

Install

pip install prized

Python 3.10 or newer. The only dependency is httpx.

Authenticate

Make an API key at prized.dev/dashboard/workspace/api-keys and put it in the environment. New to Prized? Open Sandboxes signs you up (free credit, no card) and makes one.

export PRIZED_API_KEY=dcp_…

Or pass api_key="dcp_…" to any call. The key acts as you and sees every sandbox in its workspace.

Quickstart

from prized import Sandbox

with Sandbox.create() as sb:  # returns once it runs
    result = sb.exec("python3 --version")
    print(result.stdout, result.exit_code)

    sb.files.write("hello.py", "print('hello from the sandbox')\n")
    print(sb.exec("python3 hello.py").stdout)
# leaving the block deletes the sandbox

The same with asyncio:

import asyncio
from prized import AsyncSandbox


async def main() -> None:
    async with await AsyncSandbox.create() as sb:
        result = await sb.exec("node --version")
        print(result.stdout)


asyncio.run(main())

Many at once, a few at a time: a workspace caps how many sandboxes it holds (10 on the free tier), and a sandbox being deleted still counts for a moment, so each one is gone before its slot takes the next command:

async def run_all(commands: list[str], limit: int = 4) -> list[str]:
    slots = asyncio.Semaphore(limit)  # 4 fits the free tier

    async def one(cmd: str) -> str:
        async with slots:
            async with await AsyncSandbox.create(vcpu=2, memory_gb=4, labels={"job": "batch"}) as sb:
                try:
                    result = await sb.exec(cmd, timeout=600)  # past it: CommandTimeoutError
                finally:
                    await sb.delete(wait=True)
                if result.exit_code != 0:
                    raise RuntimeError(f"{cmd!r} failed: {result.stderr}")
                return result.stdout

    # Every job settles (and deletes its sandbox) before a failure is raised.
    results = await asyncio.gather(*(one(c) for c in commands), return_exceptions=True)
    for r in results:
        if isinstance(r, BaseException):
            raise r
    return results

Reference

Everything below exists on both classes; on AsyncSandbox every method and classmethod is awaited.

Sandbox.create(template="prized-base-v1", **options) -> Sandbox

Creates a sandbox and returns once it is running, ready for commands.

If the sandbox fails to start or timeout runs out, the SDK raises PrizedError (code sandbox_error or timeout; sandbox_id set) and deletes the sandbox. A create that is interrupted (Ctrl-C, a cancelled task) or never gets an answer (timeout or network_error once its retries are spent) finds the sandbox it may have made and deletes it too.

With your own idempotency_key, the SDK deletes nothing: that key may be shared with another call holding the same sandbox. The error names the sandbox (sandbox_id); resend the create with the key to get it back, or delete it. fork() follows the same rules for its copies.

That cleanup is best effort, bounded (10 seconds for a create, a little more per copy for a fork): if Prized cannot be reached meanwhile, a sandbox may be left until its run time ends, or, if it pauses first (auto_pause_min), until you delete it (free tier: 30 days after its last use). Label your sandboxes, and Sandbox.delete_by_labels(...) deletes any leftovers once it can.

Create, pause() and resume() ask the API to answer once the change has landed, and only poll if it has not within a few seconds.

Every classmethod also takes the connection options:

Find sandboxes

sb = Sandbox.connect("sbx_…")  # any state; no waiting
mine = Sandbox.list(labels={"job": "batch"}, state="running")
templates = Sandbox.templates()  # [Template(id, defaults, min, max, ...)]

list() returns the workspace's sandboxes that are not yet deleted, newest first. labels keeps those carrying every label; state takes one state or several.

Delete by label

ids = Sandbox.delete_by_labels({"job": "batch"})  # every sandbox carrying it, in one call

delete_by_labels() needs at least one label and returns the ids it deleted. It is safe to repeat (one already deleting is listed again; none matching returns []). A sandbox being deleted still counts toward your quota until Sandbox.list(labels=...) no longer returns it.

Fields

sb.id (sbx_…), sb.state, sb.template, sb.resources (vcpu, memory_mb, memory_gb, disk_gb), sb.labels, sb.auto_pause_min, sb.auto_delete_min, sb.expires_at (when its run time ends; None while a paused sandbox's clock is stopped), sb.created_at, sb.last_active_at, sb.error_reason, and sb.info (all of it; sb.info.raw is the document as the API sent it).

States: starting, running, pausing, paused, resizing, deleting, deleted, error. Fields reflect the last answer the SDK read; sb.refresh() reads the sandbox again.

sb.exec(cmd, cwd=None, env=None, timeout=None, on_stdout=None, on_stderr=None, background=False, full_output=False, poll_outage=None)

Runs one command with bash as the user prized and returns ExecResult(stdout, stderr, exit_code, truncated, timed_out, duration_ms).

• cmd is a shell string ("ls -la | wc -l") or a list of arguments (["python3", "-c", code]), which the SDK quotes for you.
• cwd defaults to /home/prized/work; relative paths resolve against it.
• env adds variables for this command, on top of the sandbox's env_vars.
• timeout is in seconds: default 60, 0 for no limit. A command that runs past it is killed, and the call raises prized.CommandTimeoutError (a PrizedError, code command_timeout). Its result is the ExecResult with what the command printed before (also err.stdout, err.stderr), exit_code=-1 and timed_out=True.
• A non-zero exit code is a result, not an exception.
• One call keeps the first 4 MiB of stdout and of stderr, and truncated=True says when it cut one. Pass full_output=True for builds, test suites and anything else whose output you need whole: the result keeps up to 100 MiB of each stream (truncated=True past that). It is still one request when the output is small; past 4 MiB the SDK reads it back from files in /home/prized/.prized/exec/, then removes them. With it, a command a signal ends gets exit_code 128+n (a plain exec may give -1), as a background command does.
• on_stdout / on_stderr receive the output as it arrives. On AsyncSandbox they may be coroutine functions.
• A streamed command (or one with a timeout over 240 seconds, or 0) rides out a dropped connection: the SDK keeps polling it for up to poll_outage seconds (default 120, set on the call or the client) before it gives up and stops the command; a refused key, or an answer that settles it (the sandbox deleted or not running), stops it at once.

result = sb.exec("npm test", timeout=180, full_output=True)  # every line of the log
sb.exec(
    "python3 -m venv .venv && .venv/bin/pip install -r requirements.txt",
    timeout=600,
    on_stdout=lambda out: print(out, end=""),
)  # chunks keep their own newlines

Background commands

background=True starts the command and returns a CommandHandle at once. The command runs in its own session: it keeps running after your process exits, and while it runs, kill() reaches every process it started (not one that left its process group, such as a daemon). Once the command has ended, kill() returns False and signals nothing.

server = sb.exec("python3 -m http.server 8000", background=True)
server.status()  # CommandStatus(running=True, exit_code=None)
server.logs()  # CommandLogs(stdout=..., stderr=...) so far
server.kill()  # SIGTERM (or kill("SIGKILL")); False if it had exited
result = server.wait(on_stdout=lambda out: print(out, end=""))  # ExecResult once it ends
server.cleanup()  # remove its log files from the sandbox

wait(timeout=...) bounds the wait only; the command keeps running, and wait() returns what the command printed by the time it ended (not what a process it left behind prints after). Pass on_stdout/on_stderr to wait(); exec(..., background=True) refuses them. A background command has no time limit unless you pass timeout= (whole seconds); one that runs past its limit is killed, wait() raises CommandTimeoutError at once, and anything it started that ignores the TERM is killed 5 seconds later. env applies to the command itself. Background and streamed commands run with PYTHONUNBUFFERED=1 unless their environment already sets it (env={"PYTHONUNBUFFERED": ""} keeps Python's buffering), so a Python program's output arrives as it prints. Its output is kept in /home/prized/.prized/runs/ until cleanup(), which removes it once the command has ended (a command still running keeps its files, and its time limit); a command that prints without end fills the sandbox's disk there, so redirect such output yourself (> /dev/null, or a log you rotate). logs() says truncated=True when a stream passed what the SDK keeps.

sb.files

Paths are absolute or relative to /home/prized/work. write, read, upload and download work inside /home/prized.

Lifecycle

sb.pause()  # memory and disk kept (until you delete it; free tier: 30 days); no compute charged
sb.resume()  # every process carries on where it left off
kids = sb.fork(4)  # 4 new sandboxes, each a live copy of this one (running or paused)
sb.refresh()  # read the sandbox again (state and the other fields)
sb.keep_alive()  # count as activity now: the auto-pause clock starts over
sb.delete()
sb.close()  # release the SDK's connections; the sandbox keeps running

• pause() and resume() return once the sandbox is paused / running. Pass wait=False to return as soon as the API accepts, and timeout= (seconds) to bound the whole call (the request, its retries and the wait).
• A command or file call on a paused sandbox resumes it first (billed and counted as activity like any resume), so resume() is optional before one.
• fork(count=1, labels=None) works on a running or a paused sandbox. Each copy is an ordinary sandbox with its own id, its own files from then on, and the parent's memory and every process as they were at the fork (or at the pause), running. A running parent pauses briefly, usually under a second, and keeps running; a paused one stays paused. All or nothing: it returns once every copy is running; if any copy fails, or the call runs out of time (timeout=, default 180 s, the request and the wait together), every copy is deleted and PrizedError is raised. A fork that does not fit raises fork_capacity, whose message says how many copies fit now (err.body["fits"]). The copies keep the parent's labels unless you pass labels=, which gives them only the labels you pass.
• delete() returns once the API accepts; delete(wait=True) waits until the sandbox is gone (a deleting sandbox still counts toward quotas). Deleting a sandbox that is already gone is not an error.
• with Sandbox.create(...) as sb: deletes the sandbox when the block ends, error or not.

Run time

A sandbox is deleted when its run time ends (sb.expires_at). The clock counts running time only:

• Paid: 24 hours by default, up to 7 days (max_runtime_min on create). The clock stops while the sandbox is paused, and each resume starts it again with a fresh max_runtime_min. A paused sandbox is kept, memory and disk, until you delete it (or its auto_delete_min does).
• Free tier: 60 minutes of running in all. Paused time does not count, but a resume carries on the time left. A paused one is kept 30 days after its last use.
• Forks: on a paid workspace each copy gets the parent's max_runtime_min from the fork; on the free tier copies keep the parent's deletion time.
• Extend a running one with the CLI (prized sandbox extend <id> --by 2h) or the API (POST /api/v1/sandboxes/{id}/extend; see Run time). On the free tier an extend cannot move the end later.

Errors

Every failure of a call to Prized raises prized.PrizedError. Two kinds keep Python's own exceptions: arguments the SDK refuses before sending anything raise ValueError or TypeError, and files.upload() / files.download() raise OSError for the local file.

from prized import PrizedError, Sandbox

try:
    sb = Sandbox.create()
except PrizedError as err:
    if err.code in ("paid_balance_required", "insufficient_balance"):
        print("Add funds at prized.dev, then retry.")
    elif err.code == "sandbox_quota_exceeded":
        print(f"At a workspace quota ({err.reason}).")
    else:
        raise

Codes you may meet:

Retries. The SDK retries rate limits (429, honouring Retry-After), 502, 503 and 504 answers, dropped connections, and every answer a command is retried on, with backoff (0.5 s, 1 s, 2 s, …), up to max_retries times. A read (Sandbox.list, connect, refresh, templates, a file download, and the polling while create, pause, resume, fork or delete waits) is retried on any other 500 too; a write is not, since it may already have happened. A command, a files.write / files.upload, a files.remove or a kill() is sent again only when it provably never arrived: the connection never opened, or the answer says so (rate limited, the sandbox not ready). One whose answer was lost is not sent again: the command may have run, or the sandbox written the file since. Quota, balance and idempotency refusals, and the maintenance switches above, are never retried.

Did it run? When a command, a file write, a files.remove or a kill() fails without a plain refusal, the error keeps its code and its message says which of three it was. It never reached the sandbox (the connection never opened, or the answer proves it, such as sandbox_not_ready): it had no effect. No clear answer came back (a dropped connection, a timeout, or any other 5xx): it may or may not have run, and the message says how to check (read the file back, files.exists(), status()). A 2xx came back that could not be read: it ran. A background command (or a streamed or long exec, which runs as one) whose start got no clear answer is stopped by the SDK, and the error says so, or, when the SDK could not confirm the stop, that it may still be running and under which run id. So is a streamed or long exec whose polling fails while it runs (a dropped connection or a 5xx for longer than poll_outage, a refused key): the error keeps the poll's code and status, is raised from the poll's own error (__cause__), and says whether the SDK stopped the command or it may still be running. An error that settles it (the sandbox deleted or not running, the run not found) is raised as it came.

Deadlines. Retries stay within a call's bound: timeout= for create, pause, resume, fork and delete (the request, its retries and the wait, its polls included; with wait=False too), 2 minutes for connect, list, templates, refresh and keep_alive, and 10 minutes for a file transfer. Retry-After is honoured up to a minute. A retry that could not start in time is not sent: the call raises timeout. A wait's last poll goes out just before its deadline.

Limits

Pricing is per second while running, and storage only while paused: prized.dev/pricing.

Not yet: an interactive terminal from the SDK, custom templates, more than 32 vCPU or 128 GB, GPUs.

Development

cd sdk/python
python -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy && .venv/bin/pytest

The tests run against an in-memory fake of the API (tests/fake_api.py) and never touch the network. scripts/package_check.py builds the wheel and sdist and checks them as PyPI gets them. scripts/live_smoke.py drives real sandboxes end to end with PRIZED_API_KEY; it costs money and is not run in CI.

License

Apache-2.0. The full text is in the LICENSE file that ships with the package.