Checkpoints

A checkpoint is a saved copy of the disk of a sandbox. Take one before an agent tries something risky, and restore it when things go wrong. Checkpoints are kept until the sandbox is deleted, and they share unchanged blocks, so storage counts only what was written.

Every sandbox starts with v0, the fresh disk it was created with. Your checkpoints count up from v1.

The checkpoint object

{
  "id": "v3",
  "create_time": "2026-10-31T09:30:00Z",
  "comment": "deps installed",
  "source_id": null,
  "health": "ok"
}

Create a checkpoint

POST /v1/sandboxes/{name}/checkpoint

The body is optional. A comment of up to 1024 bytes labels the checkpoint.

curl -X POST $API/agent-1/checkpoint -H "$AUTH" -d '{"comment": "deps installed"}'

The sandbox can be running or not. The answer is NDJSON: progress lines while the disk is saved, then one final line.

{"type":"info","data":"...","time":"2026-10-31T09:29:58Z"}
{"type":"complete","data":{"id":"v3","create_time":"2026-10-31T09:30:00Z","comment":"deps installed","source_id":null,"health":"ok"},"time":"2026-10-31T09:30:00Z"}

A failure ends the stream with an error line instead:

{ "type": "error", "error": "...", "code": "checkpoint_failed", "time": "2026-10-31T09:30:00Z" }

The checkpoint finishes even if you disconnect before the last line. It holds what is on the disk when you ask; anything a running program keeps only in memory is not in it.

List checkpoints

GET /v1/sandboxes/{name}/checkpoints

Answers an array of checkpoints, newest first, with v0 last.

Get a checkpoint

GET /v1/sandboxes/{name}/checkpoints/{id}

Answers the checkpoint, or 404 checkpoint_not_found.

Restore a checkpoint

POST /v1/sandboxes/{name}/checkpoints/{id}/restore

curl -X POST $API/agent-1/checkpoints/v3/restore -H "$AUTH"

A restore stops the sandbox and puts the disk back as it was in the checkpoint. Running processes end and do not come back; the next request boots the sandbox on the restored disk. Checkpoints newer than the one you restore are kept, so you can move forward again.

Restore v0 to reset a sandbox to a fresh disk while keeping its name, environment and secrets.

The answer is NDJSON like a create, ending with complete or an error line with code restore_failed. A failed restore leaves the disk as it was.

Errors