# Checkpoints

> Save the disk of a sandbox at a good moment and roll back to it later.

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

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

## Create a checkpoint

```http
POST /v1/sandboxes/{name}/checkpoint
```

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

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

```json
{"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:

```json
{ "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

```http
GET /v1/sandboxes/{name}/checkpoints
```

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

## Get a checkpoint

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

Answers the checkpoint, or `404 checkpoint_not_found`.

## Restore a checkpoint

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

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

| Status or line | Code                   | When                                                         |
| -------------- | ---------------------- | ------------------------------------------------------------ |
| 400            | `bad_request`          | The body is not JSON, or the comment is over 1024 bytes.     |
| 404            | `checkpoint_not_found` | No checkpoint has this id.                                   |
| line           | `checkpoint_failed`    | The disk could not be saved. The sandbox is unchanged.       |
| line           | `restore_failed`       | The checkpoint could not be put back. The disk is unchanged. |
| line           | `stale`                | The sandbox changed while saving. Try again.                 |