Lesson 2: Snapshot and roll back

Capture an environment's disk, make a change you regret, and undo it

In the Quickstart you brought up an environment. This lesson adds the safety net: take a snapshot before doing something risky, then roll back to it.

You need the same setup as the quickstart, an orchestrator running on localhost:8080 against the stub provider, and a connected CLI. Nothing here requires a real Firecracker host.

1. Create an environment to work in

Give it a task ID you’ll recognize, and use --no-wait so the command returns:

fuse up --no-wait --task-id lesson2 --secret pg_password=devpassword

The environment’s ID is the configured prefix plus your task ID, so lesson2 becomes fuse-lesson2. That naming rule matters, most commands take the environment ID, not the task ID.

fuse environment get fuse-lesson2

2. Take a snapshot

fuse snapshot create fuse-lesson2 --comment "before risky change"

The snapshot is created synchronously and comes back ready:

mode               manual
state              ready
size               467 B
retention          keep forever
comment            before risky change

Note the ID it prints, the first one is cp-1. List them any time:

fuse snapshot list

That is a disk snapshot, which is what you get when you don’t ask for anything else. It captures the environment’s disk and nothing else, so restoring it is a reboot from that disk rather than a resume of a running process. Step 4 covers the other kind. See Snapshots for the full model.

3. Roll back

Restore returns the environment’s disk to the captured state:

fuse snapshot restore cp-1 --yes

restoring snapshot "cp-1"

--yes skips the confirmation prompt. Without it in a script the command aborts with Aborted (use --yes to skip confirmation). rather than hanging on a prompt nothing will answer.

Restore rewrites the disk of the existing environment in place, it does not create a new one. fuse environment list still shows exactly one environment afterward. If you want a copy instead of a rollback, that is a fork, which is Lesson 3.

4. Optional: capture memory too

Everything above is disk. If what you want back is the process state, a warmed cache, a loaded model, a compile halfway through, add --live:

fuse snapshot create fuse-lesson2 --live --comment "warmed up"

You get a snapshot record back exactly as before, and it goes in the same list. The difference is on the record itself: its kind is live rather than disk. Two things are worth knowing about the one you just took.

The size is much larger. A live snapshot stores the guest’s entire memory next to the disk copy, so it costs the environment’s configured memory on top of the rootfs, every time you take one. That is dense, incompressible data, and your tenant’s byte quota was sized for rootfs-only snapshots. You will notice.

The environment pauses while it is taken. The disk copy and the memory image have to be captured in the same window, with the guest stopped, or the disk the guest wakes up to would no longer match the memory it wakes up with. How long that pause lasts depends on the host’s filesystem, see Snapshots.

Restoring is the same command you already ran:

fuse snapshot restore <id> --yes

You do not tell restore which kind it is dealing with. The host agent reads the kind off the snapshot and either resumes the guest or cold-boots it. What you’ll see is the difference in how long it takes and what survives: a live restore comes back with the processes still running and the memory intact, where the disk restore in step 3 rebooted.

One thing you cannot do with a live snapshot is fork from it. Fork copies a snapshot’s disk to seed a new environment, and that is all it looks at. A live snapshot’s disk was copied without quiescing the guest filesystem, because the page cache is captured in the memory image instead, so that disk only mounts cleanly with the memory image beside it. Fork rejects a live snapshot with a 409 rather than handing you a copy that cannot boot. If you want a copy rather than a rewind, take a disk snapshot and read Lesson 3.

5. Clean up

fuse environment destroy fuse-lesson2 --yes

What to take away

Snapshots are manual. Nothing snapshots on your behalf.
Disk is the default. It captures the disk only, and restoring it reboots.
--live also captures memory and vCPU state, so restoring resumes instead of rebooting. It costs the guest’s full memory in bytes per snapshot, pauses the guest to take it, is pinned to the host that took it, and cannot be forked from.
Restore is destructive to the current disk and in-place. The snapshot survives, the environment’s current state does not.
Snapshots do not work on GPU environments at all, live or disk, a passed-through device can’t be checkpointed. See Providers.