Sandbox lifecycle

A sandbox moves through a small set of states. This page is the map: what each state means, what triggers a transition, and how to stop and restart compute without discarding the workspace.

Lifecycle

create() creates creating; creating goes to running on ready; running goes to paused on pause(), and back to running on resume().

running goes to snapshotting on snapshot(); snapshotting goes to running on saved.

running or paused goes to destroyed on destroy().

creating or running goes to error on failure; error goes to destroyed on cleanup.

State	Meaning
`creating` / `provisioning`	VM is being claimed, restored, and prepared to accept commands
`running`	Command-ready: exec, files, previews, terminal, and port exposure work
`snapshotting`	Runtime is saving filesystem and memory state for resume/fork
`paused`	CPU is stopped; memory/filesystem state is preserved for resume
`destroyed`	Terminal: resources freed, ID unusable, saved state removed
`error`	Boot or runtime failure; check `sbx.data["metadata"]` for `last_error`

Activity that resets the idle clock: exec calls, file writes, preview HTTP traffic, terminal stdin. For persistent sandboxes, once timeout_sec elapses the running session stops and the sandbox becomes paused. For explicitly non-persistent sandboxes, timeout destroys the VM and discards the filesystem.

idle_timeout_sec pauses a persistent sandbox after a period of inactivity, instead of at a fixed wall-clock deadline. It is off unless you set it; 0 disables it explicitly.

pause() and resume() are not the only way back out of paused: a paused persistent sandbox wakes on request. A request that arrives while it is paused (for example, to its preview URL) resumes it and is held until it is running, so the caller does not have to resume it explicitly.

See Persistence, pause, and forks for the full pause/resume/fork flow.

Readiness and billing

A sandbox is command-ready only in the running state. Two signals tell you when it gets there:

The ready boolean on the sandbox record. true means the VM session is prepared to accept exec, files, previews, and terminal calls.
The state field. Poll GET /api/v1/sandboxes/{id} until state leaves creating and becomes running (or surfaces error).

The fused run endpoint owns this wait on the server, so agents that create-and-exec do not need a client poll loop.

Which states cost what:

State	Billing
`creating` / `provisioning`	Preparing resources; not yet command-ready
`running`	Billed at the vCPU-second plus GiB-second rate for your plan
`snapshotting`	Runtime is saving state
`paused`	Storage rate only (disk GiB-second)
`destroyed`	Billing stops immediately

See Sizing and limits for the full billing notes and Timeouts and auto-stop for what happens at the deadline.

Pause and resume

pause() and resume() give you explicit control over the running to paused transition without destroying state.