Runtimes

A runtime is the execution backend that runs a sandbox. The default runtime is microvm. Every sandbox created before runtimes existed is a microvm.

List runtimes

The response lists every registered runtime. A runtime with status: planned is registered but cannot boot yet. Create refuses it with 501.

const { runtimes } = await client.request("GET", "/v1/runtimes");

runtimes = client.request("GET", "/v1/runtimes")["runtimes"]

# no dedicated CLI command — use pt api
pt api /v1/runtimes

curl -sS "$PT_API_URL/v1/runtimes" -H "Authorization: Bearer $PT_TOKEN"

Each entry carries key, label, status, description, and capabilities. Read capabilities before you depend on a feature. A runtime that sets exec: false does not run commands.

Select a runtime

Set runtime when you create a sandbox. Omit it for a microvm.

const sbx = await client.sandboxes.create({ template: "pt-base", runtime: "cell" });

sbx = client.sandboxes.create(template="pt-base", runtime="cell")

pt sandbox create -t pt-base --runtime cell

curl -sS -X POST "$PT_API_URL/v1/sandboxes" \
  -H "Authorization: Bearer $PT_TOKEN" -H "Content-Type: application/json" \
  -d '{"template":"pt-base","runtime":"cell"}'

The response carries runtime. An unknown runtime is a 400. A runtime that is registered but disabled in this environment is a 501 with code: runtime_not_enabled.

Filter by runtime

const { rows } = await client.sandboxes.list({ runtime: "cell" });

rows = client.sandboxes.list(runtime="cell")["rows"]

pt sandbox list --runtime cell

curl -sS "$PT_API_URL/v1/sandboxes?paginated=true&runtime=cell" -H "Authorization: Bearer $PT_TOKEN"

An unknown runtime in the filter is a 400 that names the known runtimes. It is not an empty page.

The cell runtime

A cell is a V8 isolate with a private SQLite database. The database replicates to object storage as it runs. A stopped cell holds no memory. A request rebuilds it from object storage.

A cell does not run commands, open a terminal, or expose a filesystem. Read capabilities on GET /v1/runtimes for the current list.

The cell runtime is switched off by default. An operator enables it per environment with the flags.cell_runtime_enabled setting.

Workers are folders

A cell reads one deployment from the root of its storage prefix, so the org prefix alone would mean one Worker per org and every cell in the org serving it. POST /v1/sandboxes {"runtime": "cell", "worker": "<name>"} roots the cell at workers/<name>/ under the org prefix instead — its own deploy/, cells/ and fleet/. A name is one plain path segment ([a-z0-9-], 1–63 characters, not starting with -); worker on any other runtime is refused with worker_requires_cell. GET /v1/sandboxes?worker=<name> lists that Worker's cells, and every sandbox carries worker (null = the org root).

Deploying a Worker

No storage credentials. Build the module (esbuild, as wrangler does), then:

POST /v1/workers/<name>/versions      multipart: bundle=<index.js>, manifest=<json>
  → { version, script_name, prefix }  version = first 16 hex of sha256(bundle)
POST /v1/workers/<name>/activate      { "version": "…" }
  → { cells: [...], restart_required: true }
GET  /v1/workers · GET /v1/workers/<name>

The manifest is celld's: script_name (the wrangler name), main_module, do_classes, sqlite_classes, and raw_metadata (the wrangler bindings, compatibility_date, migrations). The control plane writes deploy/<script>/<version>/{index.js,manifest.json} and, on activate, the two current.json pointers under orgs/<org>/workers/<name>/ — the folder a cell created with worker: <name> boots from. On celld 0.3.0 a cell loads a deployment at startup, so activate names the cells to stop/start; 0.4.0 adopts the pointer in place.