Skip to main content
A snapshot is a saved copy of a specific machine. It captures the disk and the memory, so a machine created from the snapshot is already running whatever the source machine was running when the snapshot was saved. The difference from a fork is speed and scalability. A fork gives you a copy of the source machine as it is at that moment. Creating a machine from a snapshot is faster, and cheaper, as you don’t need to keep a machine around to fork from. Reach for a snapshot when startup time is what matters, or when you always want to start from a core state. A machine created from a snapshot resumes in the captured state instead of booting and then starting your app, so this is the fastest way to create many identical machines. Preview environments are a clear use case, where every pull request needs the same app, ready upon creation.

A running machine saved as a named snapshot in seconds.

Save a snapshot

The machine has to be running when you save. The capture pauses it just long enough to grab the memory and disk together, then lets it carry on, so the machine keeps running the whole time. snap is the short alias, so boxd snap save myapp my-workspace does the same thing.

Create machines from it

Each machine gets its own name, URL, and SSH port, and comes up exactly where the snapshot was taken. Make as many as you want from the same snapshot. A snapshot lives in the region of the machine it was saved from, and machines created from it start in that region. boxd machine new fresh --from-snapshot my-workspace.nyc names a snapshot in New York.

Everything running comes back

A machine created from a snapshot resumes in the state you captured. Nothing boots. A web server that was listening on the source machine is already listening on the new machine, under the same PID, with the same process start time, and the machine’s uptime continues from the source machine rather than resetting. Everything the source machine had already done stays done: dependencies installed, the database warm, the dev server compiled. That is why creating machines from a snapshot stays fast even when you make a lot of them at once. Each new machine does get its own identity when it wakes. The hostname and private IP are fresh while the processes keep going, so a long-lived process that cached the source machine’s hostname or address holds a stale value on the new machine.

Automations start paused

The one exception is automations. Saving a snapshot captures the source machine’s background jobs, and every machine created from it starts them paused, the same as a fork does. Otherwise each machine created from the snapshot would run the same schedule and handle the same events as the source machine and as each other, and a team’s default snapshot would do it on every new team machine.
boxd machine new --from-snapshot says how many came along, and --json carries the count as paused_automations. On the new machine, run jobs lists them, and run restart <ID> starts one there. See Forks and snapshots.

List and remove

USED is how many machines currently came from it. STATUS is ready once machines can be created from the snapshot, which takes a moment after saving.

Saving again replaces the version

Saving over a name you already used captures a new version that replaces the previous one, and --from-snapshot always uses the latest. While the new version is saving, new machines keep being created from the previous one, and once the new version is ready the name switches over to it. Older versions are cleaned up and cannot be restored or pinned. To keep an old state, save it under a new name.
So one name can be your moving known-good marker. Keep saving over it as the machine evolves, and every new machine starts from the freshest capture.

From inside a machine

A machine can snapshot itself. Inside a machine, the CLI takes only the snapshot name and captures the machine you are in:

Who can see them

A snapshot belongs to the organization that contains the source machine and never crosses into another org. Who can see it follows the source machine. A snapshot of a shared org machine is visible to the whole org. A snapshot of a private machine is visible only to whoever captured it. A machine created from a snapshot is private to whoever created it, billed to the snapshot’s org. So another org member can take a shared snapshot and stand up their own private copy to work in, leaving the shared source machine alone. That is the same pattern as forking a shared machine.
A machine created from a snapshot is rebuilt from the captured state, so it cannot take extra disks at the same time. boxd machine new --from-snapshot ... --disk ... is refused. A disk can be attached to an existing machine only when both are on the same host, so when a machine needs a disk, pair them at creation with boxd new --disk on a fresh machine.

Compared to suspend and hibernate

Standby and hibernation also keep a machine’s memory, as a memory image that boxd manages for you to put one machine to sleep and wake it again. That image is temporary. A snapshot is named, you create and delete it yourself, and it outlives the machine. See Suspend, resume, and hibernate.