Skip to main content
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 instead.

​
Usage

Checkpoints live under machine:
The machine stays running while the checkpoint is captured. It must be running to take a checkpoint, since memory is part of the capture.

One command captures memory and disk, while the machine keeps running.

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.
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. 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, or a fork for an instant throwaway copy.