> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fly.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkpoints
Persistence keeps your filesystem across pauses on its own: you don't ask for it, and it's always there. A checkpoint is the other half. It's a save point you create on purpose, a snapshot of the filesystem at one moment that you can return to later.
Reach for a checkpoint before anything you might want to undo: a dependency upgrade, a destructive refactor, an experiment an agent runs unattended. Take the checkpoint, do the risky thing, and if it goes wrong, you can restore.
## What a checkpoint captures
A checkpoint snapshots the writable filesystem overlay: everything you've added on top of the base image. It does not touch the base image itself, and it does not capture anything that only lives in memory.
| Captured | Not captured |
| -------------------------------- | ------------------------ |
| Files and directories | Running processes |
| Installed packages | In-memory state |
| Config files and dotfiles | Open network connections |
| Databases on disk (SQLite, etc.) | |
This is the same line [Lifecycle and Persistence](/sprites/concepts/lifecycle) draws between disk and memory: disk is in the snapshot, memory is not. After a restore, [Services](/sprites/concepts/services) come back from their on-disk definitions the way they do after a cold wake. A process you started by hand does not.
## Creating a checkpoint
One command snapshots the current state and returns a versioned ID. Add a comment so the ID means something later.
```bash cmd theme={null}
sprite checkpoint create --comment "Clean Python 3.11 + Node 20 setup"
```
```output output theme={null}
Checkpoint created: v1
```
It runs copy-on-write, so it's fast and doesn't interrupt the Sprite. Work keeps going while the snapshot is taken. IDs are sequential (`v0`, `v1`, `v2`, and so on). For the full command surface, including `list`, `info`, and `delete`, see the [CLI Commands reference](/sprites/cli/commands#checkpoints).
## Restoring a checkpoint
Restoring replaces the writable overlay with the saved state and restarts the environment. The base image is untouched.
```bash theme={null}
sprite restore v1
```
`sprite restore v1` is the alias for `sprite checkpoint restore v1`. The restore is asynchronous: the command returns right away, the environment restarts, and active sessions are terminated. A following `sprite exec` automatically retries while the Sprite is still coming back up.
**Restore is destructive. Checkpoint first.**
Restoring overwrites your current filesystem with the checkpoint's, and the state you replace is not backed up for you. If there's unsaved work you want to keep, create a checkpoint before you restore. Once the restore runs, the previous state is gone unless you captured it.
## Browsing without restoring
The last five checkpoints are mounted read-only at `/.sprite/checkpoints/` inside the Sprite. You can read or diff a previous state without restoring it, which is the quick way to check what changed before you decide to roll back.
```bash theme={null}
# Compare a file against how it looked in v34
diff /.sprite/checkpoints/v34/etc/hosts /etc/hosts
```
## Automatic checkpoints
Alongside the checkpoints you take by hand, the platform creates its own in the background as you work. They're tagged automatic and given `auto-` IDs, so they stay separate from your `v0`, `v1`, `v2` series and never consume a version number.
They're hidden by default. List them with `--include-auto`:
```bash theme={null}
sprite checkpoint list --include-auto
```
You restore one exactly like any other checkpoint, by ID. Treat them as a safety net, not a plan: they carry no comment describing what they captured, and older ones are pruned over time. For anything you specifically want to be able to return to, take your own checkpoint with a comment.
## Checkpointing from inside the Sprite
Agents and scripts running inside a Sprite can manage their own checkpoints, which is what makes them useful for unattended work: snapshot before a risky step, restore if it fails, all without anything outside the Sprite coordinating it.
The `sprite-env` CLI is the simplest path:
```bash theme={null}
sprite-env checkpoints create --comment "before migration"
sprite-env checkpoints list
sprite-env checkpoints restore v4
```
Or talk to the management socket directly. `GET /v1/checkpoints` lists them; `POST /v1/checkpoint` creates one and streams progress as NDJSON.
```bash theme={null}
curl --unix-socket /.sprite/api.sock \
-H "Content-Type: application/json" \
http://sprite/v1/checkpoints
```
The self-checkpointing pattern is the payoff: checkpoint before something risky, run it, restore on failure.
```bash theme={null}
sprite-env checkpoints create --comment "pre-experiment"
# Try something that might not work
rm -rf node_modules && npm install
# If it broke, roll back to the checkpoint above
sprite-env checkpoints restore v4
```
The behavior an agent relies on is documented inside every Sprite at `/.sprite/llm.txt`, which is read-only reference, not a control file.
## Checkpoints are not version control
A checkpoint captures environment state, not code history. It's a fast undo for setup, config, and the moving parts around your work. It is not a substitute for Git, which is where your code and its history belong. Use both: commit your code, checkpoint the environment around it.
```bash theme={null}
git commit -am "Save progress"
sprite checkpoint create --comment "tests green"
```
## Storage and cleanup
Checkpoints live in durable object storage and are copy-on-write: a new checkpoint only stores the blocks that changed since the last one, so incremental snapshots stay small. You're billed for the blocks actually kept, and deleting a checkpoint frees that space right away.
A couple of rules worth knowing:
* You can't delete the checkpoint you're currently on. Restore to another one first, then delete it.
* Keep at least one known-good checkpoint as a fallback, and prune the rest periodically so old state doesn't pile up.
## Related documentation
Full reference for sprite checkpoint create, list, info, delete, and restore
How automatic persistence keeps your filesystem across pauses
Processes the runtime brings back after a restore or cold wake
Interaction modes and the filesystem in practice