Snapshots and forks

PandaStack supports two related but distinct primitives: snapshots (frozen state on disk) and forks (live copies of a running VM).

Snapshots

A snapshot captures the complete state of a microVM at a point in time:

• Guest memory (RAM contents)
• vCPU registers
• Device state (block, net, vsock)
• A copy of the rootfs (sparse, deduplicated via reflink)

$ pandastack sandboxes snapshot <id>
snap_4f7a92  created in 2.1s  (memory: 412 MiB, rootfs delta: 12 MiB)

Snapshots are stored in /var/lib/damroo/snapshots/<snap-id>/ and consist of:

• vm.mem — page-aligned guest memory (sparse)
• vm.state — vCPU + device state
• rootfs.ext4 — reflink-cloned rootfs (CoW, takes no extra space until divergence)

You can restore a sandbox from any snapshot:

$ pandastack sandboxes create --from-snapshot snap_4f7a92
$ # ↑ this sandbox boots with the EXACT same in-memory state

Templates as snapshots

Every "template" is just a snapshot baked by the agent. When you create a sandbox from code-interpreter, the agent is actually restoring from /var/lib/damroo/template-snaps/code-interpreter/. This is why cold boots are 240 ms instead of the 4–5 seconds a fresh kernel boot would take.

Forks

A fork creates a live copy of a running sandbox in ~50 ms:

parent = Sandbox(template="code-interpreter")
parent.run("python -c 'state = compute_expensive_thing()'")

# Now explore 10 different mutations in parallel
children = [parent.fork() for _ in range(10)]
for c in children:
    c.run("python -c 'mutate(state)'")

Forks use memory CoW via Firecracker's snapshot resume + rootfs CoW via XFS reflink. Until the child writes a page, that page is shared with the parent in the page cache.

When to fork vs snapshot

Forks are ephemeral (lost on agent restart). Snapshots are durable (written to disk, replicated to object storage in the managed cloud).