Sandboxes

Pause, resume, destroy

A sandbox is running, paused, lost or deleted. Pause it to stop paying for CPU and memory while keeping its disk; destroy it when you’re done.

States

Pausing and resuming pass through resuming on the way back to active. A call only succeeds when the sandbox’s current state allows it — you can’t resume a sandbox that isn’t paused, for example. If a lifecycle step fails, the sandbox reports an error.

A sandbox is lost when its VM died (for example it ran out of memory) and can’t be resumed; commands on it answer 410 sandbox_lost with the reason. Remove it with a destroy. A destroyed sandbox is deleted: its files are gone and its ID can’t be used again.

Pause

POST /session/{sandbox_id}/pause

Pausing snapshots the VM’s memory and device state along with its disk, then releases its CPU and memory on the machine. Its disk allocation is kept for when it comes back.

curl -sS -X POST "$SPAWN_API_URL/session/$SANDBOX_ID/pause" \
  -H "Authorization: Bearer $SPAWN_API_KEY"

{
  "status": "success",
  "session_id": "3ecb0221-faf1-4976-a8ae-6fd6262de59a",
  "state": "paused"
}

• The disk is checkpointed in chunks, and chunks that didn’t change since the last pause are reused — a repeat pause only stores what changed.
• Terminals attached to the sandbox are closed when it pauses.

Resume

POST /session/{sandbox_id}/resume

Resuming reserves capacity again on the same machine, restores the latest snapshot and reconnects to the agent inside. The sandbox returns to active.

curl -sS -X POST "$SPAWN_API_URL/session/$SANDBOX_ID/resume" \
  -H "Authorization: Bearer $SPAWN_API_KEY"

{
  "status": "success",
  "session_id": "3ecb0221-faf1-4976-a8ae-6fd6262de59a",
  "state": "active"
}

Destroy

DELETE /session/{sandbox_id}

Destroying deletes the VM and wipes its writable disk, releases its place on the machine and bills any final running time. A record of the sandbox stays in the destroyed state for your history and audit log, but none of its data does.

curl -i -X DELETE "$SPAWN_API_URL/session/$SANDBOX_ID" \
  -H "Authorization: Bearer $SPAWN_API_KEY"

Automatic pause and cleanup

Sandboxes don’t run forever, even if your agent forgets about them:

Both timeouts are set when you create the sandbox; the expires_at field in responses tells you when it will next pause if left idle.