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. Unlike a snapshot, 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:
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.

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

​
Reference

CLI

machine checkpoint save, list, restore, remove.

Snapshots

Named images you spin up copies from.

Fork

Instant, in-place copies of a running machine.

The VM model

Creating, listing, and what’s inside a machine.