smolvm sandbox snapshot

smolvm sandbox snapshot saves sandbox state so you can return to it later. Use snapshots before risky commands, before handing a sandbox to an agent, or after installing expensive dependencies.

Synopsis

smolvm sandbox snapshot create <sandbox> [OPTIONS]
smolvm sandbox snapshot restore <snapshot> [OPTIONS]
smolvm sandbox snapshot list [OPTIONS]
smolvm sandbox snapshot delete <snapshot> [OPTIONS]

Snapshots work on Firecracker and QEMU for Linux guests with isolated disks. Windows guests, workspace mounts, and extra drives are not supported yet.

create

Save a running or paused sandbox.

smolvm sandbox snapshot create <sandbox> \
  [--snapshot-id <id>] \
  [--snapshot-type full|diff|disk] \
  [--resume-source] \
  [--live-only] \
  [--flush-policy required|best-effort|skip] \
  [--json]

sandbox

string

required

Name or ID of the sandbox to snapshot.

--snapshot-id

string

Custom snapshot ID. If omitted, SmolVM creates one.

--snapshot-type

string

default:"full"

What to store. Use full for a complete checkpoint, diff for a smaller disk artifact, or disk for QEMU disk-only state.

--resume-source

flag

Resume the source sandbox after the snapshot is created.

--live-only

flag

Keep a running QEMU sandbox available for the whole snapshot instead of briefly pausing it. Requires --snapshot-type disk and --resume-source, and only works on QEMU. If the installed QEMU cannot do a live block backup, the command fails rather than falling back to a pause.

--flush-policy

string

default:"required"

How to handle the pre-snapshot guest filesystem flush for --snapshot-type disk. required fails the snapshot if the flush fails, best-effort continues with a crash-consistent copy, and skip does not ask the guest to flush at all.

smolvm sandbox snapshot create my-sandbox \
  --snapshot-id before-deploy \
  --resume-source

Create a QEMU disk-only snapshot:

smolvm sandbox snapshot create my-sandbox --snapshot-type disk

Take a live disk snapshot of a running QEMU sandbox without pausing the guest:

smolvm sandbox snapshot create my-sandbox \
  --snapshot-id live-checkpoint \
  --snapshot-type disk \
  --resume-source \
  --live-only

Use --flush-policy to trade durability for speed. This example keeps a sandbox running through a live snapshot and doesn’t fail if the guest agent can’t flush:

smolvm sandbox snapshot create my-sandbox \
  --snapshot-type disk \
  --resume-source \
  --live-only \
  --flush-policy best-effort

restore

Restore a snapshot back into its sandbox identity.

smolvm sandbox snapshot restore <snapshot> [--resume] [--force] [--json]

snapshot

string

required

Snapshot ID to restore.

--resume

flag

Resume the restored sandbox immediately.

--force

flag

Restore a snapshot even if SmolVM has already marked it restored.

smolvm sandbox snapshot restore before-deploy --resume

list

List snapshots, optionally filtered by source sandbox.

smolvm sandbox snapshot list [--vm-id <sandbox>] [--json]

smolvm sandbox snapshot list --vm-id my-sandbox

delete

Delete a snapshot and its files.

smolvm sandbox snapshot delete <snapshot> [--json]

Deleting a snapshot removes its saved disk, memory, and state files.

Guest sync before disk snapshots

For disk snapshots, SmolVM asks the guest to flush filesystem state before it copies the disk. Recent images answer this through the SmolVM guest agent over the control channel, with SSH as a fallback where needed. Use --flush-policy to tune this step: required (default) fails the snapshot if the flush cannot succeed, best-effort continues with a crash-consistent copy, and skip bypasses the flush entirely. If snapshot creation times out during guest sync, check Control channel and Troubleshooting before debugging storage or upload paths.

smolvm sandbox list - Find sandbox names
smolvm sandbox shell - Inspect a restored sandbox
Snapshot and restore sandboxes - Learn when to use each snapshot type

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

smolvm sandbox snapshot

Synopsis

create

restore

list

delete

Guest sync before disk snapshots

​Synopsis

​create

​restore

​list

​delete

​Guest sync before disk snapshots

​Related commands

Synopsis

create

restore

list

delete

Guest sync before disk snapshots

Related commands