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 draws between disk and memory: disk is in the snapshot, memory is not. After a restore, 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.

sprite checkpoint create --comment "Clean Python 3.11 + Node 20 setup"

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.

Restoring a checkpoint

Restoring replaces the writable overlay with the saved state and restarts the environment. The base image is untouched.

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.

# 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:

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:

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.

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.

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.

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

CLI Commands

Full reference for sprite checkpoint create, list, info, delete, and restore

Lifecycle and Persistence

How automatic persistence keeps your filesystem across pauses

Services

Processes the runtime brings back after a restore or cold wake

Working with Sprites

Interaction modes and the filesystem in practice