Skip to main content

​
Synopsis

smolvm snapshot {create,restore,delete,list} [OPTIONS]

​
Description

The snapshot command manages Firecracker VM snapshots. You can save the full state of a running VM, restore it later, list existing snapshots, and delete ones you no longer need.
Snapshots require the Firecracker backend. They are not available on QEMU.

​
Subcommands

​
create

Save the full state of a running or paused VM. 
smolvm snapshot create <vm_id> [--snapshot-id <id>] [--resume-source] [--json]
​
vm_id
string
required
The identifier of the VM to snapshot. The VM must be running or paused.
​
--snapshot-id
string
A custom identifier for the snapshot. If omitted, SmolVM generates one automatically (for example, snap-my-vm-1717012345). Must contain only lowercase letters, numbers, and hyphens.
​
--resume-source
flag
Resume the source VM after the snapshot is created. Without this flag, the VM stays paused.
​
--json
flag
Output machine-readable JSON instead of human-friendly text.
Example: 
smolvm snapshot create my-vm --snapshot-id before-deploy --resume-source
Example output: 
Created snapshot 'before-deploy' from VM 'my-vm'.

​
restore

Restore a snapshot back into its original VM identity. 
smolvm snapshot restore <snapshot_id> [--resume] [--force] [--json]
​
snapshot_id
string
required
The identifier of the snapshot to restore.
​
--resume
flag
Resume the restored VM immediately. Without this flag, the VM is restored in a paused state.
​
--force
flag
Allow restoring a snapshot that was already restored before. By default, a snapshot can only be restored once.
​
--json
flag
Output machine-readable JSON instead of human-friendly text.
Example: 
smolvm snapshot restore before-deploy --resume
Example output: 
Restored snapshot 'before-deploy' into VM 'my-vm'.

​
delete

Delete a snapshot and its associated files. 
smolvm snapshot delete <snapshot_id> [--json]
​
snapshot_id
string
required
The identifier of the snapshot to delete.
​
--json
flag
Output machine-readable JSON instead of human-friendly text.
Deletion is permanent. The snapshot’s state, memory dump, and disk copy cannot be recovered.
Example: 
smolvm snapshot delete before-deploy

​
list

List all snapshots, optionally filtered by source VM. 
smolvm snapshot list [--vm-id <vm_id>] [--json]
​
--vm-id
string
Filter the list to show only snapshots created from this VM.
​
--json
flag
Output machine-readable JSON instead of human-friendly text.
Example: 
smolvm snapshot list
Example output: 
  Snapshot ID        VM ID     Restored   Created At
  before-deploy      my-vm     No         2026-04-03T12:30:00
  pre-experiment     agent-1   Yes        2026-04-03T11:15:00

Total: 2 snapshot(s).
Filter by VM: 
smolvm snapshot list --vm-id my-vm

​
JSON output

All subcommands support --json for scripting and automation. The JSON response includes snapshot metadata such as snapshot_id, vm_id, restored, created_at, and file paths. Example: 
smolvm snapshot create my-vm --snapshot-id test-snap --json

{
  "command": "snapshot.create",
  "exit_code": 0,
  "data": {
    "snapshot": {
      "snapshot_id": "test-snap",
      "vm_id": "my-vm",
      "restored": false,
      "restored_vm_id": null,
      "created_at": "2026-04-03T12:30:00+00:00",
      "snapshot_path": "/home/user/.local/state/smolvm/snapshots/test-snap/vmstate.bin",
      "mem_file_path": "/home/user/.local/state/smolvm/snapshots/test-snap/mem.bin",
      "disk_path": "/home/user/.local/state/smolvm/snapshots/test-snap/disk.ext4"
    }
  }
}

​
Exit codes

CodeDescription
0Success
1Error (snapshot not found, VM not running, etc.)
2Usage error (missing subcommand or arguments)
Last modified on April 3, 2026