> ## 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
> Per-machine save points 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 image you can share and spin up copies from, use a [snapshot](/guides/snapshots) instead.
## Usage
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 vs 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 image |
| Restore | **In place**: the same machine rolls back | Creates a **new** machine (`--from-snapshot`) |
| Leaves the machine | No, it stays private to its machine | Yes, share it and spin up copies |
| Outlives the machine | No, it is deleted with it | Yes, it survives destroying it |
| Limit | Up to 10 per machine | Versioned; no hard cap |
| Best for | Undo before a risky change | Golden images and fast fan-out |
Rule of thumb: a **checkpoint** is "let me undo this machine"; a **snapshot** is "let me stamp out copies of this machine."
## Limits and lifecycle
* **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 stays private to it. For an image you can copy or share, use a snapshot.
* **They die with the machine.** Destroying 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 and stays private to it.
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 this enables
* **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 box.** 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.