> ## 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. Unlike a [snapshot](/how-it-works/snapshots), a checkpoint isn't a reusable image and never leaves the machine: you restore it **in place**, rolling the same machine back to exactly that state. Think of it as an undo button before a risky change.
## 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)
```
Saving doesn't interrupt the machine -- it stays `running` while the checkpoint is captured. The machine must be `running` to check it (memory is part of the capture). The name is optional; leave it off and boxd generates one like `checkpoint-3f9a1c`.
Inside a machine, the SDK 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). See the [in-VM CLI](/reference/internal-cli).
## Restore is in place
Restoring a checkpoint doesn't create a new machine -- it **rewinds the one you 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 nothing about the machine's identity changes; from the inside it's 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 -- files, database rows, running work -- is discarded, and open connections drop while the machine restarts. It returns to exactly where the checkpoint was taken, not to where it is now.
## Checkpoint vs snapshot
They look similar -- both capture memory + 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** -- same machine rolls back | Creates a **new** machine (`--from-snapshot`) |
| Leaves the machine | No -- can't be copied or shared | Yes -- share it, spin up copies |
| Outlives the machine | No -- deleted with it | Yes -- 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 -- it can't be copied, shared, or turned into a reusable image.
* **They die with the machine.** Destroying a machine removes its checkpoints. There's nothing to clean up separately, and nothing left behind to bill for.
* **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 -- fast enough that the machine barely notices, and no restart.
2. **Keep it with the machine.** The capture is stored with the machine itself. It's never copied elsewhere or promoted to a shareable image -- a checkpoint is private to its machine, always.
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 a checkpoint is 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 -- no re-provisioning.
* **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; return to it whenever you paint yourself into a corner.
Want copies that persist and that you can share, instead of an in-place undo? Use a [snapshot](/how-it-works/snapshots) -- or a [fork](/how-it-works/fork) for an instant throwaway copy.
## Reference
`machine checkpoint save`, `list`, `restore`, `remove`.
Named images you spin up copies from.
Instant, in-place copies of a running machine.
Creating, listing, and what's inside a machine.