Checkpoints

Checkpoints let you save a named disk state while a sandbox is running. Restore creates a new sandbox from that checkpoint using the same class, template version, network policy, ports, and metadata as the source sandbox.

Create a checkpoint

curl https://api.watasu.io/v1/sandboxes/123/checkpoints \
  -X POST \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkpoint-001" \
  -d '{
    "sandbox_checkpoint": {
      "name": "after-install",
      "quiesce_mode": "guest",
      "expires_at": "2026-06-02T12:00:00Z",
      "metadata": {
        "reason": "agent prepared workspace"
      }
    }
}'

You can also use the snapshot-named alias:

curl https://api.watasu.io/v1/sandboxes/123/snapshots \
  -X POST \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "after-install", "quiesce_mode": "guest" }'

quiesce_mode controls how Watasu prepares the guest before snapshotting:

Mode	Behavior
guest	Ask the guest to flush filesystem state before the disk checkpoint.
crash	Capture the disk checkpoint without guest quiescing.

List checkpoints

curl https://api.watasu.io/v1/sandboxes/123/checkpoints \
  -H "Authorization: Bearer $WATASU_API_KEY"

List snapshots across the teams visible to your API key:

curl "https://api.watasu.io/v1/sandbox_snapshots?limit=100" \
  -H "Authorization: Bearer $WATASU_API_KEY"

Filter the global snapshot list by source sandbox:

curl "https://api.watasu.io/v1/sandbox_snapshots?sandbox_id=123&limit=100" \
  -H "Authorization: Bearer $WATASU_API_KEY"

The response includes checkpoint id, name, status, local state, quiesce mode, size, expiry, metadata, and creation time.

Delete a checkpoint

Delete through either the sandbox-scoped checkpoint/snapshot route or the global snapshot route:

curl https://api.watasu.io/v1/sandboxes/123/snapshots/456 \
  -X DELETE \
  -H "Authorization: Bearer $WATASU_API_KEY"

curl https://api.watasu.io/v1/sandbox_snapshots/456 \
  -X DELETE \
  -H "Authorization: Bearer $WATASU_API_KEY"

Restore from a checkpoint

Pass the returned snapshot_id as template_id when creating a sandbox. Watasu resolves normal templates first; if the value is not a template, it is treated as a snapshot id visible to the selected team. The create response includes a fresh data-plane session.

curl https://api.watasu.io/v1/sandboxes \
  -X POST \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sandbox-from-snapshot-001" \
  -d '{
    "team": "acme",
    "template_id": "456",
    "timeout": 3600
  }'

You can also use the explicit snapshot_id or checkpoint_id field:

{
  "team": "acme",
  "snapshot_id": 456,
  "timeout": 3600
}

The older sandbox-scoped restore endpoint is still available:

curl https://api.watasu.io/v1/sandboxes/123/restore \
  -X POST \
  -H "Authorization: Bearer $WATASU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: restore-001" \
  -d '{
    "restore": {
      "checkpoint_id": 456,
      "timeout": 3600
    }
  }'

Restore returns the new sandbox instance. Connect to the restored sandbox to receive a fresh data-plane session token:

curl https://api.watasu.io/v1/sandboxes/<restored-sandbox-id>/resume \
  -X POST \
  -H "Authorization: Bearer $WATASU_API_KEY"

Billing

Checkpoint storage is billed by size and time until the checkpoint expires or is removed by lifecycle cleanup. See Sandbox Billing.