Skip to content
docs.microagent.sh

Snapshot and fork workspaces

Last updated: 2026-06-27

A snapshot freezes a workspace - guest memory, device state, and disk - at one moment. Use it to roll back a workspace in place, or fork independent copies that resume from the same checkpoint. If the host cannot save and restore VM memory, snapshot create fails with a structured error before writing a partial checkpoint.

1. Get a workspace into a state worth keeping

Section titled “1. Get a workspace into a state worth keeping”
Terminal window
microagent create builder --image docker.io/library/alpine:3.20
microagent start builder
microagent exec builder -- sh -c "echo checkpoint-1 > /root/progress.txt"

2. Take the snapshot

Section titled “2. Take the snapshot”
Terminal window
microagent snapshot create builder --tag baseline
snapshot baseline created (512 MiB RAM, 2 vCPU) at 2026-06-11T08:52:44Z

A running workspace is briefly auto-paused, snapshotted, and resumed; an already-paused one is snapshotted in place and left paused. --tag defaults to a timestamp, and one workspace can hold many tags:

Terminal window
microagent snapshot list builder
TAG                      SIZE         CREATED               IMAGE
baseline                 1.5GiB       2026-06-11T08:52:44Z  docker.io/library/alpine:3.20

Each snapshot stores the VM state plus a full rootfs copy, so size is roughly saved guest state plus the disk. snapshot delete reclaims the space.

3. Restore in place

Section titled “3. Restore in place”

start --from-snapshot rolls the same workspace back: memory, devices, and disk return to the snapshot point, and everything since is discarded.

Terminal window
microagent halt builder
microagent start builder --from-snapshot baseline
microagent exec builder -- cat /root/progress.txt
checkpoint-1

This is the checkpoint workflow: snapshot before a risky upgrade, restore if it goes wrong.

4. Fork new workspaces from it

Section titled “4. Fork new workspaces from it”

create --from-snapshot <workspace>:<tag> makes a new workspace from the same moment - fresh identity, private copy of the rootfs, resumed from the snapshot’s memory:

Terminal window
microagent create builder-fork --from-snapshot builder:baseline
microagent exec builder-fork -- sh -c "echo fork-only > /root/progress.txt"
microagent exec builder-fork -- cat /root/progress.txt
microagent exec builder -- cat /root/progress.txt
fork-only
checkpoint-1

The fork diverges; the source doesn’t notice. Fork as many as you like from one tag - pay for boot and setup once, stamp out warm copies. Networked forks use user mode (the default): each fork gets its own per-VM network namespace, so any number run concurrently.

5. Know the contract

Section titled “5. Know the contract”
  • Same kernel. The manifest records the kernel sha256; restore and fork refuse a different kernel.
  • Connections reset. Host networking is re-established fresh on restore and fork, so in-flight TCP and vsock sessions (exec, shell, mediation) do not survive - the guest process is expected to reconnect.
  • Secrets are scrubbed. Workspaces with delivered secrets get /run/secrets purged before the memory file is written and rehydrated on resume, restore, and fork - see deliver secrets.

Clean up

Section titled “Clean up”
Terminal window
microagent halt builder-fork && microagent delete builder-fork --yes
microagent halt builder
microagent snapshot delete builder baseline
microagent delete builder --yes

Deleting a workspace also removes its snapshots; snapshot delete removes a single tag.

Section titled “Related”