Skip to main content
A snapshot is a saved copy of a specific machine. It captures the disk and the memory, so a machine booted from the snapshot is already running whatever the original machine was running (at time of snapshotting). The difference from a fork is speed and scalability. A fork gives you a second machine of the parent at any given point in time. Booting from a snapshot is faster, and much cheaper, as you don’t need to keep a machine running 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 wakes into the captured state instead of booting and then starting your app, so this is the fastest way to spin up 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.

​
Everything running comes back

A machine created from a snapshot wakes straight into the state you captured. A web server that was listening on the original 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 original rather than resetting. Everything the original 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 original’s hostname or address holds a stale value on the new machine.

​
List and remove

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

​
Saving again makes a new version

Saving over a name you already used captures a new version, and --from-snapshot always restores the latest one. New machines keep coming from the previous version until the fresh capture is ready, and once it is, the older version is cleaned up.
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

Machines can snapshot themselves. Leave the machine name out and it uses the one 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 a teammate can take a shared snapshot and stand up their own private copy to work in, leaving the shared original alone. That is the same pattern as forking a shared machine.
A restore rebuilds the machine from the captured state, so it cannot take extra disks at the same time. boxd machine new --from-snapshot ... --disk ... is refused. Create the machine first, then attach the disk.

​
Compared to suspend and hibernate

Suspend and hibernate also capture memory, but boxd manages those for you to freeze and wake one machine, and they are temporary. A snapshot is named, you create and delete it yourself, and it outlives the machine. See Suspend, resume, and hibernate.