# Checkpoints

> Capture sandbox disk state and restore it into a new sandbox.

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.

Checkpoints capture the **disk** — they are for branching, archiving, and
spawning fresh sandboxes from a known state. If you want one sandbox to stop
and later continue exactly where it was, with its running processes intact,
use [pause and resume](https://docs.watasu.io/sandboxes/overview.md#lifecycle) instead: pause preserves
the whole machine, not just the files.

## Create a checkpoint

Checkpoints expire 24 hours after creation by default. Set `expires_at` to use an
explicit deadline. Storage billing ends at expiry; physical cleanup is automatic
and retried if the owning node is temporarily unavailable.

```bash
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:

```bash
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

```bash
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:

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

Filter the global snapshot list by source sandbox:

```bash
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:

```bash
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` 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.

```bash
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": "watasu",
    "template": "456",
    "timeout": 3600
  }'
```

You can also use the explicit `snapshot_id` or `checkpoint_id` field:

```json
{
  "team": "watasu",
  "snapshot_id": 456,
  "timeout": 3600
}
```

The older sandbox-scoped restore endpoint is still available:

```bash
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:

```bash
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](https://docs.watasu.io/sandboxes/billing.md).

[View this page on the web](https://docs.watasu.io/sandboxes/checkpoints/)