Guides

Snapshots & forks

A snapshot is a saved copy of a box’s disks — installed software, repos, sign-ins, everything under /data. Start new boxes from it, restore a box back to it, or skip the snapshot and fork a box directly.

What a snapshot holds

• The root disk (what you installed) and /data (your home, workspaces and saved sign-ins for git, gh and your agents).
• Not memory, and not running processes. A box started from a snapshot boots fresh on those disks.
• Snapshots are private to the workspace that made them. Deleting a box keeps its snapshots; deleting a snapshot doesn’t touch boxes started from it.

Save one, start from it

moil snapshot dev --name dev-base
moil create --name dev2 --from dev-base
moil snapshot ls

moil snapshot waits until the copy is saved. A running box keeps running while it is saved; anything a program hasn’t written to disk yet may be left out, so stop the box first when you need an exact copy. A paused box has to be resumed or stopped before it can be saved.

Set up once, start many

The usual pattern: start a box, clone your repos, install dependencies, sign your agent in, then save it as base. Every run after that starts from --from base and skips the setup entirely.

Fork a box

moil fork dev                        # one copy, named dev-1
moil fork dev --count 3 --json       # dev-1, dev-2, dev-3

fork copies a running or stopped box on the host it already lives on — no snapshot in between — and boots the copies, usually in a few seconds. Each copy has the same template and size and a new name. Memory and processes are not copied, and the source box carries on untouched.

• Up to 5 copies per call. Each one counts toward your plan’s running limit.
• A paused box can’t be forked: resume or stop it first.

Let attempts race

Fork right before a risky step, try a different approach in each copy, and keep the winner:

moil fork run-42 --count 3
for i in 1 2 3; do
  moil exec run-42-$i -- ./attempt.sh --strategy $i &
done
wait
moil rm run-42-2 run-42-3 --yes     # keep the one that passed

Restore in place

moil restore dev --snapshot dev-base
moil restore dev --yes               # back to the snapshot dev was created from

restore puts a box’s disks back to a snapshot without making a new box. It keeps its ID, name and public URLs, so whatever points at it keeps working; everything written since the snapshot is gone. It asks before it does anything — --yes skips the question. To keep the box as it is and get a second one, use create --from or fork.