Snapshots and pausing

Pause and resume

POST /v1/sandboxes/{sandbox_id}/pause freezes the sandbox's vCPUs and keeps its memory and disk on the node. POST /v1/sandboxes/{sandbox_id}/resume continues exactly where it stopped: processes carry on, open files stay open, and the guest clock is corrected. Pausing a paused sandbox, or resuming a running one, returns it unchanged.

bash
curl -s -X POST "https://beta-api.b3os.org/v1/sandboxes/$SBX/pause" -H "Authorization: Bearer $B3OS_API_KEY"curl -s -X POST "https://beta-api.b3os.org/v1/sandboxes/$SBX/resume" -H "Authorization: Bearer $B3OS_API_KEY"

A paused sandbox bills no CPU time and still expires at expires_at. Whether it bills memory while paused is still being settled for the beta; the sandbox's usage shows what it was charged. Create a sandbox with on_idle: "pause" to have it pause instead of stopping when its time runs out; extend the timeout, then resume it.

The target for pause and for resume is 1 ms each; see benchmarks.

Save a snapshot

POST /v1/sandboxes/{sandbox_id}/snapshot saves the sandbox's memory and disk. The sandbox pauses for the copy, then keeps running:

bash
curl -s -X POST "https://beta-api.b3os.org/v1/sandboxes/$SBX/snapshot" \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{"name": "deps-installed"}'

ts
const snapshot = await b3os.sandboxes.createSnapshot(sbx, { name: "deps-installed" });console.log(snapshot.id, snapshot.status, snapshot.size_bytes);

python
snapshot = b3os.sandboxes.create_snapshot(sbx, {"name": "deps-installed"})print(snapshot["id"], snapshot["status"], snapshot["size_bytes"])

text
Install the project's dependencies in my sandbox with npm ci.

A snapshot keeps the template, sizes and contents of its sandbox. Its status is creating, then ready (or failed; the sandbox keeps running unchanged and you can retry). Snapshots are kept for 7 days in the beta.

Start from a snapshot

Pass the snapshot instead of a template:

bash
curl -s https://beta-api.b3os.org/v1/sandboxes \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{"snapshot": "snap_01m5t5mnvax7tp9peav8jajw3y"}'

The new sandbox starts with the snapshot's processes and files in memory, already running. Each sandbox restored from a snapshot gets a fresh identity (new entropy, machine ID and clock), so two of them never share random state, and the same snapshot can start many sandboxes. Use this to install dependencies once and start every later sandbox warm.

GET /v1/sandboxes/snapshots lists your snapshots, GET /v1/sandboxes/snapshots/{snapshot_id} returns one, and DELETE removes one; sandboxes already restored from it keep running.

Templates are snapshots too

Templates (base, code-interpreter, agent) are snapshots B3OS prepares and keeps resident on the node. Creating a sandbox from a template claims one of a pool of microVMs already restored from it, which is why creation does not wait for a boot. GET /v1/sandboxes/templates lists them.

Fork

Forking a running sandbox into several copies that share memory and disk copy-on-write is planned for later in the beta. Until a node serves it, POST /v1/sandboxes/{sandbox_id}/fork answers 501 not_implemented. Sandboxes meant to be forked are created with forkable: true.