Lesson 3: Fork to reproduce a bug

Copy a running environment so you can break the copy safely

Lesson 2 rewound one environment in place. This lesson makes a second environment from the first, which is what you want when something is misbehaving and you’d rather investigate a copy than the original.

Why fork instead of restore

Restore rewinds the environment you already have, and the state you were debugging is gone. Fork leaves the original untouched and gives you a duplicate to take apart. For a production incident that distinction is the whole point, you keep the evidence and experiment on the copy.

1. Start from a running environment

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

2. Fork it

fuse environment fork fuse-lesson3 --comment repro

Fork snapshots the source first, then provisions a brand-new environment from that snapshot. The copy gets a generated ID rather than one you choose:

fuse-fork-4da004cb6c97435c53074fbd9a141849

Both are now running, and the original is unchanged:

fuse environment list

ID                                          STATE     TASK ID
fuse-lesson3                                running   lesson3
fuse-fork-4da004cb6c97435c53074fbd9a141849  running   fork-4da004cb...

To fork from a snapshot you already took, rather than taking a fresh one, pass --reuse-snapshot <id>.

3. Investigate the copy

The fork is an ordinary environment, so the usual commands take its ID:

fuse environment exec fuse-fork-4da004cb... -- cat /var/log/app.log
fuse environment shell fuse-fork-4da004cb...

4. Clean up both

fuse environment destroy fuse-fork-4da004cb... --yes
fuse environment destroy fuse-lesson3 --yes

Three things that surprise people

A fork cold-boots. Fork reads a snapshot’s disk and nothing else, so the copy boots from that disk rather than resuming the source’s memory. Expect a normal boot, not a sub-second resume, and don’t expect in-memory state to carry over. This holds even if you forked from a live snapshot: fork sees its disk half only.

Setup and run do not re-execute. The fork starts from the captured disk, so the setup and run commands from the Fusefile are not run again on the copy. Whatever they produced is already baked into the disk you forked.

The fork gets its own credentials. It is a distinct environment with its own guest token, not a clone that shares the original’s identity.