Skip to main content
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] \
  [--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.
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

​
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. If snapshot creation times out during guest sync, check Control channel and Troubleshooting before debugging storage or upload paths.
Last modified on June 24, 2026