Sandbox lifecycle

A sandbox has a small, explicit lifecycle. Every state is observable via GET /v1/sandboxes/{id}.

States

State	Meaning	Meter
`running`	Live microVM; can exec, fork, suspend, delete.	On (per-second CPU/RAM/disk).
`suspended`	Snapshotted to disk; RAM reclaimed; resumable by id.	Off — snapshot storage only.
`deleted`	Destroyed; resources reclaimed; id no longer valid.	Off.

Transitions

                 fork ──► N children (each running)
                  ▲
 create ──► running ──► suspend ──► suspended
                  │         ▲            │
                  │         └── resume ──┘
                  └──────── delete ─────► deleted

create — POST /v1/sandboxes forks a warm template and returns a running sandbox with an id. See the sandboxes quickstart.
exec — POST /v1/sandboxes/{id}/exec runs work in a running sandbox. Execs are serialized within one sandbox; files and processes persist between them. See Running code.
fork — POST /v1/sandboxes/{id}/fork live-forks a running sandbox into N copy-on-write children that keep its process memory. The parent stays running. See Live fork.
suspend — POST /v1/sandboxes/{id}/suspend snapshots the sandbox to disk, reclaims its RAM, and stops the meter. See Suspend & resume.
resume — POST /v1/sandboxes/{id}/resume restores a suspended sandbox back to running.
delete — DELETE /v1/sandboxes/{id} destroys the sandbox and reclaims everything.

Reaping and session caps

A sandbox counts against your tier's concurrent-sandbox limit while it is running. The Demo tier allows 2 concurrent sandboxes. Pro and Enterprise have no concurrency limit: they are built for extreme width, and capacity scales with your workload. Suspending frees a slot and pauses billing without losing state. Your tier also sets a maximum session duration, covered in Limits.

Inspecting a sandbox

curl https://api.collimate.ai/v1/sandboxes/sbx_9f2a1c7b3e40 \
  -H "Authorization: Bearer $COLLIMATE_API_KEY"

{
  "id": "sbx_9f2a1c7b3e40",
  "template": "python",
  "state": "running",
  "age_secs": 42.5,
  "idle_secs": 1.2,
  "exec_count": 7,
  "labels": { "run": "grpo-step-14" }
}

List all of your tenant's sandboxes with GET /v1/sandboxes.