> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkpoints
> A checkpoint is a save point of one machine that you can roll back to in place.
A checkpoint is a save point for a single machine: its full **memory and disk** captured at a moment in time. It stays on the machine, and you restore it **in place**, rolling that same machine back to exactly the captured state. Think of it as an undo button you press before a risky change. For a reusable state that you can share and use as a starting point, use [snapshots](/guides/snapshots) instead.
## Save and restore a checkpoint
Checkpoints live under `machine`:
```bash theme={"theme":"github-dark"}
boxd machine checkpoint save myapp before-migration # capture memory + disk (machine keeps running)
boxd machine checkpoint list myapp # name, status, size, created, available (alias: ls)
boxd machine checkpoint restore myapp before-migration # reboot the machine into that state (-y to skip confirm)
boxd machine checkpoint remove myapp before-migration # delete a checkpoint (-y; alias: rm)
```
The machine stays `running` while the checkpoint is captured. It must be `running` to take a checkpoint, since memory is part of the capture.
Inside a machine, the CLI exposes the same commands: `boxd machine checkpoint save` defaults to the current machine when you omit the name. Restore and remove ask for confirmation (`-y` to skip).
## Restore is in place
Restoring a checkpoint **rewinds the machine you already have**. The machine keeps its name, HTTPS domain, SSH port, and IP. boxd swaps the checkpoint's memory and disk back in and restarts the machine into that state. From the outside the machine's identity is unchanged. From the inside it is back at the captured moment.
```bash theme={"theme":"github-dark"}
boxd machine checkpoint save myapp good # mark a known-good point
# ... run a migration, a refactor, an agent ...
boxd machine checkpoint restore myapp good # something broke? roll straight back
```
Restore is a **reboot into the captured state**. Anything written after the checkpoint, including files, database rows, and running work, is discarded, and open connections drop while the machine restarts. The machine returns to exactly where it was when the checkpoint was taken.
## Checkpoint compared to snapshot
Both capture the memory and disk of a running machine, but they solve different problems.
| | **Checkpoint** | **Snapshot** |
| - | - | - |
| Scope | One machine's save point | A reusable, named snapshot |
| Restore | **In place**: the same machine rolls back | Creates a **new** machine (`--from-snapshot`) |
| Leaves the machine | No, it stays with its machine | Yes, share it and create machines from it |
| Outlives the machine | No, it is deleted with it | Yes, it survives deleting the machine |
| Limit | Up to 10 per machine | Latest version only per name, no hard cap on names |
| Best for | Undo before a risky change | Starting points and fast fan-out |
Rule of thumb: a **checkpoint** rolls one machine back, and a **snapshot** creates new machines from a saved state.
## Limits
* **Up to 10 checkpoints per machine.** At the limit, remove one before saving another.
* **They stay with the machine.** A checkpoint belongs to its machine and cannot be moved to another one. For a reusable state you can share, use a snapshot.
* **They are deleted with the machine.** Deleting a machine removes its checkpoints too, so cleanup is automatic and billing ends with the machine.
* **Access follows the machine.** A checkpoint is part of a machine you already control: if you can act on the machine, you can act on its checkpoints.
## How it works
1. **Capture.** boxd briefly pauses the machine to record its memory and disk, then resumes. The pause is short enough that the machine barely notices, and it keeps running the whole time.
2. **Keep it with the machine.** The capture is stored with the machine itself.
3. **Restore.** boxd swaps the captured memory and disk back over the machine's current state and restarts it into that exact moment, on the same name, URL, and ports. New requests wait for the restart, then hit the rolled-back machine.
Capture and restore are both fast, so checkpoints are cheap to take often. Save one before anything you might want to undo.
## What to use it for
* **Safe experiments.** Save a checkpoint, run a destructive migration or refactor, and roll back instantly if it goes wrong.
* **Agent guardrails.** Checkpoint before handing a machine to an agent. If the run goes sideways, restore and try again from a clean point.
* **Iterate on one machine.** Keep a "good" checkpoint as you work and return to it whenever you get stuck.
Want copies that persist and that you can share, instead of an in-place undo? Use a [snapshot](/guides/snapshots), or a [fork](/guides/fork) for an instant throwaway copy.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.