Checkpoints, rewind and branch

What it is

Every command an agent runs becomes an undo point.

Turn on checkpoints and FlashVMM saves the whole VM, memory and disk, before every command. Rewind to any step under the same name, or branch new VMs from it to try several paths at once. Each checkpoint stores only the memory pages and disk blocks that differ from its base, so a checkpoint per command stays light.

Why it matters

Agents make mistakes, and they notice them late. Many commands in, one early step broke the build. A snapshot of "right now" is already wrong. Checkpoints keep the history of the VM, every step labeled with its command, and any step can be pinned to keep it for good.

• Undo for anything. Deleted files, broken installs, wrecked processes: rewind, and the VM is back exactly as it was.
• Branch from the past. Start new VMs from any checkpoint, one per idea, while the original keeps running untouched.
• Automatic. One flag checkpoints every flash exec and every MCP flash_exec.

Runs on

• Linux x86_64
• Linux arm64
• macOS
• Windows x64
• Windows arm64

How it works

Turn checkpoints on once; list, rewind and branch them from the CLI, an AI's MCP tools or the host API.

CLI

flash run --bundle BUNDLE --id agent-1 --vcpus 1 --mem-mib 512 --checkpoints --detach
flash exec agent-1 -- sh -c 'cd /work/project && sh run-tests.sh'
flash history agent-1
flash rewind agent-1 3
flash fork agent-1 --from 3 --count 2

MCP

flash_exec(vm_id: "agent-1", argv: ["sh", "-c", "sh run-tests.sh"], checkpoint: true)
flash_host(method: "GET", path: "/v1/host/flashvms/agent-1/checkpoints")
flash_host(method: "PATCH", path: "/v1/host/flashvms/agent-1", body: {checkpoint: 3})
flash_host(method: "POST", path: "/v1/host/flashvms", body: {from: {flashvm: "agent-1", checkpoint: 3}, count: 2})

API

GET   /v1/host/flashvms/{vm_id}/checkpoints
POST  /v1/host/flashvms/{vm_id}/checkpoints
PATCH /v1/host/flashvms/{vm_id} {"checkpoint": 3}
POST  /v1/host/flashvms {"from": {"flashvm": "agent-1", "checkpoint": 3}, "count": 2}

The result

An agent's mistake, undone: same VM, same name, files and memory exactly as they were.

From that same moment, two branches each try a different fix, and one finds it. The agent explores freely, because no step is ever final.