@prized/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,626 @@
-# Temporary Holding Version
+# Prized Sandboxes (beta): TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create sandboxes (microVMs your code runs in) from TypeScript: run commands,
+move files, pause for the price of storage, resume where you left off, and
+fork a running or paused sandbox into many live copies.
+
+```ts
+import { Sandbox } from '@prized/sdk';
+
+const sandbox = await Sandbox.create({ template: 'prized-base-v1' });
+const { stdout } = await sandbox.exec('python3 -c "print(6 * 7)"');
+console.log(stdout); // 42
+await sandbox.delete();
+```
+
+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](#install)
+- [Authentication](#authentication)
+- [Create, connect, list](#create-connect-list)
+- [Run commands](#run-commands)
+- [Background commands](#background-commands)
+- [Files](#files)
+- [Pause, resume, refresh, delete](#pause-resume-refresh-delete)
+- [Run time: extend anytime](#run-time-extend-anytime)
+- [Fork](#fork)
+- [Templates](#templates)
+- [Errors](#errors)
+- [Retries and timeouts](#retries-and-timeouts)
+- [Limits](#limits)
+- [Runtimes](#runtimes)
+- [License](#license)
+
+## Install
+
+```sh
+npm install @prized/sdk
+```
+
+No runtime dependencies. ESM and CommonJS, with type declarations.
+
+## Authentication
+
+Make an API key on the [API keys page](https://prized.dev/dashboard/workspace/api-keys)
+and put it in `PRIZED_API_KEY`, or pass it in. New to Prized?
+[Open Sandboxes](https://prized.dev/onboarding/sandboxes) signs you up (free
+credit, no card) and makes one.
+
+```ts
+const sandbox = await Sandbox.create({ apiKey: 'dcp_…' });
+```
+
+The key acts as you and sees every sandbox in your workspace. A key limited
+to fewer permissions needs **Sandboxes: Write** to create, run commands and
+move files; **Sandboxes: Read** is enough for `list`, `connect`, `refresh` and
+`templates`.
+
+Every entry point (`create`, `connect`, `list`, `deleteByLabels`, `templates`) takes the same
+client options:
+
+| Option | Default | |
+|---|---|---|
+| `apiKey` | `process.env.PRIZED_API_KEY` | |
+| `baseUrl` | `https://api.prized.dev` | The API origin. |
+| `edgeUrl` | the sandbox's own `toolboxBase` | Where commands and files go. |
+| `fetch` | global `fetch` | Bring your own (for a proxy, custom agent, tests). |
+| `maxRetries` | `3` | See [Retries](#retries-and-timeouts). |
+| `requestTimeoutMs` | `60000` | Per API request. |
+| `pollIntervalMs` | `500` | The longest the SDK's own polling goes between checks of the sandbox (the first come sooner). It does not cover the request itself, or the time the API holds a create, pause or resume for you (up to 8 seconds). |
+| `pollOutageMs` | `120000` | How long a streamed or long `exec` keeps polling through a dropped connection (or a 5xx, or a rate limit) before it stops the command. `exec` takes it per call too. |
+
+A sandbox remembers the options it was made with: its methods need none.
+
+## Create, connect, list
+
+### `Sandbox.create(options?)`
+
+Creates a sandbox and resolves once it is `running`, ready for commands.
+
+```ts
+const sandbox = await Sandbox.create({
+  template: 'prized-agent-v1',                       // default 'prized-base-v1'
+  resources: { vcpu: 2, memoryGb: 4, diskGb: 20 },   // or memoryMb: 4096; omitted fields take the template default
+  envVars: { NODE_ENV: 'test' },                     // for every command in the sandbox
+  labels: { job: 'nightly', owner: 'ci' },           // filter on them in Sandbox.list
+  maxRuntimeMin: 120,                                // run time in minutes; deleted when it ends (paid: 24 h by default, up to 7 days)
+  autoPauseMin: 15,                                  // pause after 15 idle minutes (0: never)
+  autoDeleteMin: 60,                                 // delete 60 minutes after pausing (0: never)
+  timeoutMs: 180_000,                                // the request, its retries and the wait for running
+  idempotencyKey: 'nightly-2026-10-14',              // a retried create returns the same sandbox
+});
+```
+
+Commands and file transfers count as activity for `autoPauseMin`.
+
+A large shape (more than 16 vCPU or about 58 GB of memory) can take a minute
+or two to start: give such a `create` a `timeoutMs` of `300_000` or more.
+
+If the sandbox fails to start or is not running within `timeoutMs`, it is
+deleted and `create` throws (`sandbox_error` with the `reason`, or
+`timeout`). 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. `wait: false`
+resolves as soon as the API accepts the create (state `starting`), still
+within `timeoutMs`. Every create carries an idempotency key (the SDK makes
+one when you give none), so the SDK's own retries never make a second
+sandbox.
+
+### Many at once
+
+Run a batch a few at a time, not all at once: a workspace caps how many
+sandboxes it holds (10 on the free tier), and a quota refusal is not retried.
+Each worker waits for its sandbox to be gone before it takes the next
+command, because a deleting sandbox still counts for a moment. If a command
+fails, the other workers finish the one they hold and stop, and `runAll`
+throws once every sandbox is deleted.
+
+```ts
+async function runAll(commands: string[], limit = 4): Promise<string[]> {
+  const out: string[] = [];
+  let next = 0;
+  let failed = false;
+  const worker = async () => {
+    try {
+      while (!failed && next < commands.length) {
+        const i = next++;
+        const sandbox = await Sandbox.create({ resources: { vcpu: 2, memoryGb: 4 }, labels: { job: 'batch' } });
+        try {
+          const r = await sandbox.exec(commands[i], { timeoutMs: 600_000 });
+          if (r.exitCode !== 0) throw new Error(`${commands[i]} exited ${r.exitCode}: ${r.stderr}`);
+          out[i] = r.stdout;
+        } finally {
+          await sandbox.delete({ wait: true });
+        }
+      }
+    } catch (err) {
+      failed = true; // the other workers finish the command they hold, then stop
+      throw err;
+    }
+  };
+  // allSettled, not all: every sandbox is deleted before runAll returns or throws.
+  const results = await Promise.allSettled(Array.from({ length: Math.min(limit, commands.length) }, worker));
+  for (const r of results) if (r.status === 'rejected') throw r.reason;
+  return out;
+}
+```
+
+### `Sandbox.connect(id, options?)`
+
+An existing sandbox by id, in whatever state it is in.
+
+```ts
+const sandbox = await Sandbox.connect('sbx_0123456789abcdef');
+if (sandbox.state === 'paused') await sandbox.resume();
+```
+
+### `Sandbox.list(options?)`
+
+Your workspace's sandboxes, newest first (deleted ones are left out).
+Filter by labels (all must match) and state:
+
+```ts
+const mine = await Sandbox.list({ labels: { job: 'nightly' }, state: ['running', 'paused'] });
+await Promise.all(mine.map((s) => s.delete()));
+```
+
+### `Sandbox.deleteByLabels(labels, options?)`
+
+Deletes every sandbox carrying all of `labels` (at least one) in one call and
+resolves with their ids. It is safe to repeat (one already deleting is listed
+again; none matching resolves `[]`). A sandbox being deleted still counts
+toward your quota until `Sandbox.list({ labels })` no longer returns it.
+
+```ts
+const ids = await Sandbox.deleteByLabels({ job: 'nightly' });
+```
+
+### What a sandbox knows
+
+```ts
+sandbox.id          // 'sbx_…'
+sandbox.state       // 'starting' | 'running' | 'pausing' | 'paused' | 'resizing' | 'deleting' | 'deleted' | 'error'
+sandbox.template    // 'prized-base-v1'
+sandbox.resources   // { vcpu, memoryMb, memoryGb, diskGb }
+sandbox.labels
+sandbox.createdAt   // Date
+sandbox.expiresAt   // Date: when its run time ends (null while a paused sandbox's clock is stopped)
+sandbox.errorReason // why it is in 'error', when it is
+sandbox.info        // all of the above, plus autoPauseMin, autoDeleteMin, lastActiveAt, raw
+```
+
+These reflect the last answer from the API; `await sandbox.refresh()` reads
+them fresh.
+
+## Run commands
+
+### `sandbox.exec(command, options?)`
+
+Runs a command and resolves with its output. `command` is a shell string, or
+an argv array the SDK quotes for you.
+
+```ts
+const r = await sandbox.exec('npm test', {
+  cwd: 'app',                 // relative paths start in /home/prized/work (the default cwd)
+  env: { CI: '1' },           // for this command, on top of the sandbox's envVars
+  timeoutMs: 120_000,         // default 60 000; 0 = no limit
+});
+r.stdout;      // string
+r.stderr;      // string, kept separate
+r.exitCode;    // number
+r.durationMs;
+r.truncated;   // true if stdout or stderr hit the 4 MiB per-call cap
+
+await sandbox.exec(['git', 'commit', '-m', "it's done"]); // quoted for you
+```
+
+One call keeps the first 4 MiB of stdout and of stderr, and `truncated` says
+when it cut one. Pass `fullOutput: true` for builds, test suites and anything
+else whose output you need whole: the result keeps up to 100 MiB of each
+stream (`truncated` 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 `exitCode` 128+n (a plain exec may give -1), as a background command
+does.
+
+```ts
+const { stdout, exitCode } = await sandbox.exec('npm test', { timeoutMs: 180_000, fullOutput: true });
+```
+
+A non-zero exit code is not an error: check `exitCode`. A command that runs
+past its timeout is killed, and the call throws `CommandTimeoutError` (a
+`PrizedError` with `code` `command_timeout`) whose `result` has what the
+command printed before (`exitCode: -1`, `timedOut: true`):
+
+```ts
+import { CommandTimeoutError } from '@prized/sdk';
+
+try {
+  await sandbox.exec('npm test', { timeoutMs: 120_000 });
+} catch (err) {
+  if (err instanceof CommandTimeoutError) console.log(err.result.stdout);
+  else throw err;
+}
+```
+
+Otherwise the SDK throws only when the command could not be run (see
+[Errors](#errors)).
+
+Stream output as it arrives with `onStdout` / `onStderr`:
+
+```ts
+await sandbox.exec('npm install', {
+  timeoutMs: 600_000,
+  onStdout: (chunk) => process.stdout.write(chunk),
+  onStderr: (chunk) => process.stderr.write(chunk),
+});
+```
+
+How it runs: a command with no callbacks and a timeout up to 4 minutes is
+one request that answers when the command finishes. With `onStdout` /
+`onStderr`, a longer timeout, or `timeoutMs: 0`, the SDK starts the command
+in the background and polls its output instead, so a long build is never cut
+off by an idle connection and its output is never truncated. The result is
+the same either way. If the connection drops meanwhile, the SDK keeps
+polling for up to 2 minutes (`pollOutageMs`, 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.
+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.
+
+Commands run as the user `prized` (home `/home/prized`, no sudo). The
+templates come with git, curl, Python 3 with pip and venv, Node 22 with npm
+and pnpm; `prized-agent-v1` adds Claude Code and Codex. Install what else
+you need into your home: Python packages into a venv
+(`python3 -m venv ~/.venv && ~/.venv/bin/pip install numpy`; plain
+`pip install`, `--user` too, is refused), and `npm` with a user prefix.
+
+## 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, survives a pause and resume, and while it runs, a kill reaches every
+process it started (not one that left its process group, such as a daemon).
+Once the command has ended, `kill()` resolves false and signals nothing.
+
+```ts
+const server = await sandbox.exec('npm run dev', { background: true, cwd: 'app' });
+server.id;    // 'run_…'
+server.pid;   // its process group id inside the sandbox
+
+await server.status();  // { running: true, exitCode: null }
+await server.logs();    // { stdout, stderr }: everything printed so far
+
+await server.kill();             // SIGTERM to the command and its children; resolves false if it had already exited
+await server.kill('SIGKILL');
+
+const job = await sandbox.exec('make build', { background: true, timeoutMs: 30 * 60_000 });
+const result = await job.wait({
+  onStdout: (chunk) => process.stdout.write(chunk),  // replays from the start, then live
+  timeoutMs: 45 * 60_000,                            // bounds the wait only; the command keeps running
+});
+result.exitCode;
+await job.cleanup();  // remove its output files from the sandbox
+```
+
+A background command has no time limit unless you give `timeoutMs`
+(enforced to the second: the command gets SIGTERM, then SIGKILL five seconds
+later, and `wait()` throws `CommandTimeoutError`). Its output is kept under
+`~/.prized/runs/<id>/` in the sandbox (`stdout`, `stderr`, `exit`) until you
+call `cleanup()` after the command has ended: after `wait()` resolves or
+throws `CommandTimeoutError` (after a `kill()`, await `wait()` first). On a
+command still running, `cleanup()` does nothing. After it, the handle's
+calls reject with `not_found`. A command that prints without end fills the
+sandbox's disk there, so redirect such output yourself.
+`exitCode` is `-1` when a command timed out or ended without reporting one
+(for example after `SIGKILL`).
+
+## Files
+
+`sandbox.files` reads and writes the sandbox's disk. Paths are absolute or
+relative to `/home/prized/work`. Writes, reads, uploads and downloads must
+stay inside `/home/prized`, are at most 100 MiB each, and do not follow
+symbolic links. A write replaces the file whole, and a file it replaces keeps
+its mode, so a script made executable stays executable; a new file gets the
+sandbox's default (`0600` in `prized-base-v1` and `prized-agent-v1`). `mode` sets the permission
+bits.
+
+```ts
+await sandbox.files.write('app/main.py', 'print("hi")\n');   // string, Uint8Array, ArrayBuffer or Blob; parents are created
+await sandbox.files.write('app/run.sh', '#!/bin/sh\necho hi\n', { mode: 0o755 }); // executable from the start
+const text = await sandbox.files.read('app/main.py');        // UTF-8 string
+const bytes = await sandbox.files.readBytes('/home/prized/work/out.bin'); // Uint8Array
+
+const entries = await sandbox.files.list('app');             // default: /home/prized/work
+// [{ name, path, size, isDir, isSymlink, mode: '-rw-r--r--', modified: Date }]
+
+await sandbox.files.exists('app/main.py');                   // true
+await sandbox.files.remove('app/old.txt');                   // a missing path is fine
+await sandbox.files.remove('build', { recursive: true });    // directories need recursive
+
+// Node, Bun and Deno: copy local files in and out
+await sandbox.files.upload('./dist/bundle.js', 'app/bundle.js');
+await sandbox.files.download('app/report.html', './report.html'); // parent directories are created
+```
+
+## Pause, resume, refresh, delete
+
+```ts
+await sandbox.pause();      // keeps memory and disk (until you delete it; free tier: 30 days); only storage is billed. Resolves when paused.
+await sandbox.resume();     // every process carries on where it was. Resolves when running.
+                            // (A command or file call on a paused sandbox resumes it too.)
+await sandbox.refresh();    // read the sandbox again (state, labels, …); not counted as activity
+await sandbox.keepAlive();  // count as activity now: the autoPauseMin idle clock starts over
+await sandbox.delete();     // resolves once accepted; the sandbox goes deleting, then deleted
+await sandbox.delete({ wait: true }); // also wait until it is gone
+```
+
+`pause` and `resume` take `{ wait: false }` to return without waiting, and
+`{ timeoutMs }` to bound the request, its retries and the wait.
+`delete`'s `{ timeoutMs }` (default 120 000) bounds the whole call. A sandbox that is deleting still counts
+toward your workspace's sandbox quota until it is gone.
+
+## Run time: extend anytime
+
+A sandbox is deleted when its run time ends. On a paid plan that is 24 hours
+by default (`maxRuntimeMin` on create), up to 7 days, and every resume
+restarts the clock with a fresh `maxRuntimeMin`; a paused sandbox's clock
+does not run, and it is kept, memory and disk, until you delete it (or its
+`autoDeleteMin` does). On the free tier it is 60 minutes of running in all:
+paused time does not count, a resume carries on the time left, and a paused
+one is kept 30 days after its last use.
+
+Change it while the sandbox runs with the CLI or the API
+([Sandbox API: Run time](https://prized.dev/docs/sandboxes-api#run-time)):
+
+```sh
+prized sandbox extend sbx_0123456789abcdef --by 2h    # add 2 hours; never shortens (POST /api/v1/sandboxes/{id}/extend)
+prized sandbox timeout sbx_0123456789abcdef --in 30m  # deleted 30 minutes from now; may shorten (POST …/timeout)
+```
+
+On a paid plan an extend stops at 7 days from now; on the free tier neither
+moves the end later.
+
+<!-- Held while sandbox ports at a URL are switched off: this section stays
+out of the rendered README until they are on. In the change that turns them
+on, delete these five lines and the closing line after the section, take
+"a sandbox's ports at a URL" out of "Not yet" under Limits, and delete the
+test "the README holds A port at a URL" (test/preview.test.ts).
+## A port at a URL
+
+`sandbox.previewUrl(port)` is the https URL a port of the sandbox answers at:
+a web app, an API, or a dev server listening on that port in the sandbox on
+`127.0.0.1` or `0.0.0.0`. HTTP, websockets and server-sent events are
+forwarded. A request needs a workspace-wide API key with Sandboxes: Write in
+the `Prized-Key` header (`previewHeaders()`; the header never reaches your
+app).
+
+```ts
+await sandbox.exec('nohup python3 -m http.server 3000 >/dev/null 2>&1 &');
+const page = await fetch(sandbox.previewUrl(3000), {
+  headers: sandbox.previewHeaders(),
+  redirect: 'manual', // never resend your key to wherever a redirect points
+});
+```
+
+Keep `redirect: 'manual'`. `fetch` sends a header like `Prized-Key` on to
+any host a redirect names (so do axios, got, Python's requests and
+`curl -L`), so a redirect from your app could hand that host your API key.
+The preview URL keeps a redirect on its own origin: a `Location` on
+`localhost:<port>` (where your app sees itself) comes back as that path on
+the preview URL, and one that points anywhere else comes back as
+`Prized-Location` instead, which no client follows. To follow a redirect,
+resolve its `Location` against the preview URL and send `previewHeaders()`
+again only when the result has the preview URL's origin, scheme included.
+Call preview URLs from server-side code: a browser hides `Location` from
+`'manual'`.
+
+Nothing is created: the URL is the sandbox's own, and every port has one
+(but 22 and 81). A request to a paused sandbox resumes it and waits up to 10
+seconds for it, as `exec` does; send `Prized-Auto-Resume: false` to get
+`503` instead. `previewUrl` throws `preview_unavailable` where this is not
+turned on.
+-->
+
+## Fork
+
+`sandbox.fork({ count })` copies a **running or paused** sandbox into `count`
+new sandboxes. Each copy has the parent's disk and every one of its processes
+running, and is an ordinary sandbox from then on: its own id, its own
+billing, its own pause, resume and delete. A paused parent stays paused.
+The copies keep the parent's labels unless you pass `labels`, which gives
+them only the labels you pass.
+
+```ts
+await sandbox.exec('git clone https://github.com/acme/app && cd app && npm ci');
+const copies = await sandbox.fork({ count: 4, labels: { role: 'worker' } });
+const results = await Promise.all(copies.map((copy, i) => copy.exec(`cd app && npm test -- --shard=${i + 1}/4`)));
+await Promise.all(copies.map((copy) => copy.delete()));
+```
+
+`fork` resolves once every copy is running. It is
+all or nothing: if any copy fails, or the wait runs out, every copy is
+deleted and `fork` throws (the parent is left as it was). It takes
+`wait: false`, `timeoutMs` (the request and the wait together), and
+`idempotencyKey` like `create`. While forking is paused for maintenance it
+answers `sandbox_fork_disabled`: retry later.
+
+On a paid workspace each copy gets a fresh lifetime from the fork: the
+parent's `maxRuntimeMin` by default, or `maxRuntimeMin` on the fork (up to
+the workspace's maximum). On the free tier, copies keep the parent's
+deletion time by default; `maxRuntimeMin` can only shorten it. Read each
+copy's deletion time from its `expiresAt`.
+
+## Templates
+
+```ts
+const templates = await Sandbox.templates();
+// [{ id: 'prized-base-v1', defaults: { vcpu, memoryMb, memoryGb, diskGb }, min, max, durability, defaultMaxRuntimeMin }]
+```
+
+| Template | What is in it |
+|---|---|
+| `prized-base-v1` | Ubuntu, git, curl, build tools, Python 3, Node 22 |
+| `prized-agent-v1` | everything in base, plus Claude Code and Codex (bring your own credentials) |
+
+## Errors
+
+Every failure is a `PrizedError`:
+
+```ts
+import { PrizedError, Sandbox } from '@prized/sdk';
+
+try {
+  await Sandbox.create();
+} catch (err) {
+  if (err instanceof PrizedError) {
+    err.status;    // HTTP status, or null when nothing came back
+    err.code;      // machine-readable: branch on this
+    err.message;   // a sentence for people
+    err.reason;    // finer detail, when there is one
+    err.sandboxId; // the sandbox it concerns, when there is one
+  }
+}
+```
+
+| `code` | Status | Meaning |
+|---|---|---|
+| `paid_balance_required` | 409 | The workspace has only free credit, and sandboxes need a paid balance right now. Add funds or pick a paid plan. |
+| `insufficient_balance` | 409 | The balance is empty. |
+| `sandbox_quota_exceeded` | 429 | A workspace quota is full; `reason` says which: `sandbox_limit`, `paused_limit`, `running_vcpu`, `running_memory`, `retained_disk`, `max_runtime`. Paused sandboxes don't count toward `sandbox_limit`, but they keep their disk, so delete the ones you no longer need, or ask for more. On the free tier the body says `"tier": "free"` and gives `limit` in the reason's unit (a count, vCPU, MB, GB, minutes; `err.body?.limit`): a top-up lifts it. |
+| `template_not_found` | 404 | No such template. |
+| `invalid_resources` | 422 | The shape is outside the template's bounds, or past the free tier's per-sandbox size (`"tier": "free"` and `limit`, in vCPU or MB, in the body); `reason` names the field. |
+| `unauthorized` / `token_expired` | 401 | The API key was refused. |
+| `key_access_denied` | 403 | The key lacks the Sandboxes permission. |
+| `not_found` | 404 | No such sandbox (or file) visible to this key. For a sandbox, most often one deleted when its run time ended; the message names it. |
+| `sandbox_not_running` | 409 | The sandbox is not running and the call could not wake it: it is resizing (`refresh()` until it leaves `resizing`, then retry), failed, or being deleted. A paused sandbox is resumed by any command or file call. The SDK never turns waking off; a request that carries `Prized-Auto-Resume: false` (added by a custom `fetch`, say) gets this for a paused or starting sandbox too: drop the header to let the call wake it and wait. |
+| `sandbox_not_ready` | 503 | A paused or starting sandbox did not reach running within the edge's 10-second wait. The wait starts when the edge, having checked the key, finds the sandbox not running, and calls with the same key arriving during it share it, so a later call may wait less. Nothing ran; retry. |
+| `parent_not_running` | 409 | Only a running or paused sandbox can be forked. |
+| `parent_not_forkable` | 409 | This sandbox cannot be forked. `reason` `resized_while_paused`: it has no memory to copy; resume it, then fork it. `reason` `parent_too_big`: its machine cannot hold even one copy beside it; fork a smaller sandbox. |
+| `fork_capacity` | 409 | The parent's machine has room for only `fits` more copies (`err.body?.fits`). If `fits` is above 0, fork that many or fewer; or try again later, or start a new sandbox and fork that one, keeping the parent until it runs. The new sandbox and each copy count toward your quota: at the limit, delete sandboxes you no longer need with `delete({ wait: true })` (a deleting sandbox still counts), or top up on the free tier. Copy out what you need first, and never delete a parent while a copy forked from it is still starting. |
+| `fork_unsupported_host` | 409 | The parent's machine cannot start copies of it. With `reason` `host_retiring` (`err.reason`), the machine is being replaced: it keeps the parent but starts no new sandboxes, so no retry or smaller `count` helps. Create a new sandbox, set it up again, and fork that one. |
+| `sandbox_capacity` | 503 | No sandbox capacity is free right now. Nothing was created or billed; the SDK retries it after `Retry-After`. |
+| `sandbox_fork_disabled` | 503 | Forking is paused for maintenance; retry later. |
+| `sandboxes_disabled` / `sandbox_create_disabled` | 503 | Sandboxes are switched off right now. |
+| `rate_limited` | 429 | Too many requests (retried for you, honouring `Retry-After`). |
+| `sandbox_unreachable` | 502 | The sandbox did not answer. A command may or may not have run. |
+| `path_outside_root` / `path_not_absolute` / `invalid_path` | 403 / 400 | A file path outside `/home/prized`, or with `..`. |
+| `file_too_large` | 413 | Over the 100 MiB transfer limit. |
+| `idempotency_conflict` | 409 | The idempotency key was used for a different request. |
+| `sandbox_error` | | The sandbox failed while you waited; `reason` says why. |
+| `sandbox_deleted` | 410 | The sandbox was deleted before or while a command or file call ran; a command that was running stopped with it. `pause()` and `resume()` of a sandbox being deleted throw it too. Not retried. A wait that finds the sandbox deleted throws it too, with no status. |
+| `command_timeout` | | A command ran past its own `timeoutMs` and was killed. Thrown as `CommandTimeoutError`; `err.result` has what it printed. |
+| `timeout` | | A wait ran past its `timeoutMs`, or a call past its bound ([Retries](#retries-and-timeouts)). One that ended because a retry could not start in time says what the last attempt met (also in `cause`). |
+| `network_error` | | No answer: the API or the sandbox could not be reached, or the connection dropped. |
+| `bad_response` | 2xx | An answer the SDK could not read. For a command or file write it did happen, and the message says so. |
+| `missing_api_key` / `invalid_api_key` / `invalid_argument` | | Fix the call. `invalid_api_key`: the key has characters no key has (the docs' placeholder, a stray character); it is never quoted back. |
+| `command_failed` | | A file helper (`list`, `remove`, `exists`) failed in the sandbox; `message` has its stderr. |
+
+## Retries and timeouts
+
+- Reads, state changes (`pause`, `resume`, `delete`, `keepAlive`),
+  downloads, and creates and forks (which always carry an idempotency key)
+  are retried up to `maxRetries` times on a dropped connection, on 429, 502,
+  503 and 504, and on every answer a command is retried on (below), with
+  exponential backoff and jitter, honouring `Retry-After`. 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. Quota, balance and switched-off refusals are never retried.
+- Retries stay within a call's bound: `timeoutMs` for `create`, `pause`,
+  `resume`, `fork` and `delete` (the request, its retries and the wait, its
+  polls included; with `wait: false` too), twice `requestTimeoutMs` (2
+  minutes by default) for `connect`, `list`, `templates`, `refresh` and
+  `keepAlive`, 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
+  throws `timeout`. A wait's last poll goes out just before its deadline.
+- A command, an upload (`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). If an
+  answer is lost after it was delivered, the SDK throws
+  (`sandbox_unreachable`, `network_error`, `timeout`) rather than risk running a command
+  twice or overwriting what the sandbox wrote to the file since.
+- Did it run? When a command answered in one call (`exec` without
+  `background`, `onStdout` or `onStderr`, and a `timeoutMs` other than 0 and
+  at most 4 minutes), a file write or a `files.remove` fails without a plain refusal,
+  the error keeps its `code` (a 2xx it could not read is `bad_response`)
+  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()`). A 2xx came back that could not be read
+  (`bad_response`): it ran. A `kill` says the same of its signal
+  (`status()` tells you whether the command is still running). 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 `pollOutageMs`, a
+  refused key): the error keeps the poll's `code` and `status`, has the
+  poll's own error as its `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 thrown as it came.
+- Deleting what a failed create or fork made (a few seconds) comes on top
+  of `timeoutMs`.
+- `create`, `exec` and waits take an `AbortSignal` (`signal`). Aborting a
+  `create` or a handle's `wait()` stops the call, not the sandbox or the
+  command (`handle.kill()` stops a command). Aborting an `exec` stops its
+  command too, as does anything else that ends a streamed or long one early
+  (an `onStdout` that throws, say): the call rejects once the SDK has tried
+  to stop it (a round trip or two; it gives up after about 20 seconds). With
+  `background: true` that covers the start only. The `aborted` error says
+  what became of the command: it never reached the sandbox (aborted before
+  it was sent); it may or may not have run, or run in part, since the
+  sandbox kills a command (and its process group) whose connection closes;
+  it ran (its answer had begun to arrive); or the SDK stopped its run, or
+  could not.
+- A `create` or `fork` that may have made sandboxes it never handed back
+  deletes them, as a failed create does (in the background; the call rejects
+  at once): one aborted mid-request, or one where any attempt got no answer,
+  a 5xx other than a refusal, or an answer the SDK could not read, even if a
+  later retry was refused (rate limited, say). The SDK finds them by sending
+  the idempotency key again, after any `Retry-After` (up to a minute). With
+  your own `idempotencyKey` they are left instead, since that key may name an
+  earlier call's sandboxes: resend the call with the key to get them back.
+  This cleanup is best effort: if Prized cannot be reached, or stops taking
+  new sandboxes meanwhile (`sandbox_create_disabled`), one may be left until
+  its run time ends, or, if it pauses first (`autoPauseMin`), until you
+  delete it (free tier: 30 days after its last use). Label your sandboxes, and `Sandbox.list({ labels })`
+  finds any leftovers.
+
+## Limits
+
+| | |
+|---|---|
+| Shape | up to 32 vCPU, 128 GB memory and 128 GB disk per sandbox, within each template's bounds (`Sandbox.templates()`) |
+| Run time | paid plans: 24 hours by default, up to 7 days, restarting on every resume; the free tier: 60 minutes of running in all. Extend anytime with the CLI or API |
+| Paused | kept until you delete it; on the free tier, 30 days after its last use |
+| `autoPauseMin`, `autoDeleteMin` | 0 (never) to 40 320 (28 days) |
+| Labels | up to 32; keys up to 64 characters, values up to 256 |
+| `envVars` | up to 32; names up to 64 characters, values up to 16 KiB |
+| Command output | 4 MiB per stream for one blocking call, 100 MiB with `fullOutput: true` (background and streamed commands have no cap) |
+| One blocking command | up to 4 minutes in the SDK (longer timeouts run in the background automatically) |
+| File transfers | 100 MiB per read or write, inside `/home/prized` |
+| Fork | up to 256 copies per call, within your quotas |
+
+Quotas per workspace (sandboxes, running vCPU and memory, retained disk,
+runtime) are on the pricing and docs pages at prized.dev; a create or resume
+past one fails with `sandbox_quota_exceeded`.
+
+Not yet: custom templates (from a Dockerfile), egress allow and deny lists,
+a sandbox's ports at a URL, more than 32 vCPU or 128 GB, GPUs, and regions
+other than US West.
+
+## Runtimes
+
+Node 18 or newer, Bun, Deno, and edge runtimes with a global `fetch`.
+`files.upload` and `files.download` need a local file system (Node, Bun,
+Deno); everywhere else use `files.write` and `files.readBytes`. Keep your
+API key on a server: never ship it to a browser.
+
+## License
+
+Apache-2.0. The full text is in the `LICENSE` file that ships with the package.