Skip to main content
Snapshots let you save a sandbox and bring it back later. This is useful when you want to keep a configured environment, retry a failed step, or checkpoint an agent’s progress before a risky operation. A full snapshot captures the VM’s CPU state, memory, and disk. When you restore it, the sandbox resumes where it was when you created the snapshot.
Snapshots are available on Firecracker and QEMU for Linux guests that use isolated disks. Windows guests, workspace mounts, and extra drives are not supported yet. QEMU snapshots require a qcow2 per-VM disk, so raw QEMU disks created for grow_filesystem=True cannot be snapshotted.

​
When to use snapshots

  • Checkpoint before risky operations — Save state before an agent runs untrusted code, so you can roll back if something goes wrong.
  • Reuse a configured environment — Set up a sandbox with the right packages and files, snapshot it, and restore it multiple times instead of repeating setup.
  • Speed up agent workflows — Skip boot and configuration time by restoring from a ready-to-go snapshot.

​
Create a snapshot

To create a snapshot, the VM must be running or paused. SmolVM pauses the VM during snapshot creation and optionally resumes it afterward. 
from smolvm import SmolVM

vm = SmolVM()
vm.start()

# Install packages and configure the environment
vm.run("apk add python3 py3-pip")
vm.run("pip install requests")

# Save the current state
snapshot = vm.snapshot(snapshot_id="my-checkpoint")
print(f"Snapshot created: {snapshot.snapshot_id}")

vm.close()
By default, the VM stays paused after a snapshot. Pass resume_source=True to keep working with it:
snapshot = vm.snapshot(
    snapshot_id="my-checkpoint",
    resume_source=True,
)
# VM is still running — you can continue using it
result = vm.run("echo 'still running'")
If you omit snapshot_id, SmolVM generates one automatically (for example, snap-my-vm-1717012345).

​
Choose a snapshot type

When you create a snapshot, you can pick how much of the VM to store:
  • full (default) — Saves a complete, self-contained disk copy plus the guest’s memory and CPU state. Use this when you want to resume the sandbox exactly where you left off.
  • diff — Saves a smaller disk artifact. On QEMU, the snapshot state is stored inside the qcow2 artifact and the backing image must still exist at restore time. On Firecracker, SmolVM still captures memory and VM state in full, and uses a copy-on-write disk copy when the host filesystem supports it.
  • disk — On QEMU, saves only the disk and skips the memory dump. Restoring boots the sandbox fresh from that disk instead of resuming the exact running process state. Use this when you only need filesystem state and a cold boot is acceptable.
On Firecracker, VM state and memory files are captured for every snapshot type. This means disk is mainly useful on QEMU today.
QEMU disk snapshots are much faster and use less space than full because they skip the RAM dump. They are the right choice for suspend/restore workflows where you only need the filesystem state.
from smolvm import SmolVM

vm = SmolVM()
vm.start()

# Space-saving snapshot — stores only what changed since the base image
snapshot = vm.snapshot(
    snapshot_id="nightly-checkpoint",
    snapshot_type="diff",
)
print(snapshot.snapshot_type)  # SnapshotType.DIFF

vm.close()
You can also pass the SnapshotType enum for type safety:
from smolvm import SnapshotType

snapshot = vm.snapshot(snapshot_type=SnapshotType.DIFF)
Take a QEMU disk snapshot when you want to save the filesystem state quickly and don’t need to resume the running process state: 
from smolvm import SmolVM, SnapshotType

vm = SmolVM(backend="qemu")
vm.start()
vm.run("apk add python3")

# Fast, lightweight snapshot — disk only, no RAM
snapshot = vm.snapshot(
    snapshot_id="cold-boot-checkpoint",
    snapshot_type=SnapshotType.DISK,
)

# Later — restoring boots the sandbox fresh from the saved disk
vm = SmolVM.from_snapshot("cold-boot-checkpoint", resume_vm=True)
result = vm.run("python3 --version")  # python3 is already installed
If the backing image for a QEMU diff snapshot is missing at restore time, SmolVM raises a clear error pointing to the missing path and suggesting you take a full snapshot instead. To stay safe, keep backing images in place while their diff snapshots exist.

​
Restore a snapshot

Restoring a snapshot recreates the original VM with the saved state. The restored VM starts in a paused state by default. 
from smolvm import SmolVM

# Restore and resume the VM in one step
vm = SmolVM.from_snapshot("my-checkpoint", resume_vm=True)
print(f"Restored VM: {vm.vm_id}")
print(f"Status: {vm.status}")  # VMState.RUNNING

# The VM is back exactly where it was
result = vm.run("python3 -c 'import requests; print(requests.__version__)'")
print(result.output)

vm.close()
A snapshot can only be restored once by default. If you need to restore the same snapshot again, use the force flag: 
vm = SmolVM.from_snapshot("my-checkpoint", resume_vm=True, force=True)

​
List snapshots

from smolvm import SmolVMManager

with SmolVMManager() as sdk:
    snapshots = sdk.list_snapshots()
    for snap in snapshots:
        print(f"{snap.snapshot_id}  vm={snap.vm_id}  restored={snap.restored}")
Filter by source VM:
snapshots = sdk.list_snapshots(vm_id="my-vm")

​
Delete a snapshot

Deleting a snapshot removes the saved state files and metadata. You cannot delete a snapshot while a restored VM from that snapshot is still running. 
from smolvm import SmolVMManager

with SmolVMManager() as sdk:
    sdk.delete_snapshot("my-checkpoint")
Deleting a snapshot is permanent. SmolVM removes the saved files for that snapshot, including any disk, VM state, and memory artifacts that snapshot type created.

​
Full example: checkpoint and retry

This example shows how an agent can checkpoint a sandbox before running untrusted code, then roll back if something fails. 
from smolvm import SmolVM, SmolVMError

# Set up a sandbox
vm = SmolVM()
vm.start()
vm.run("apk add python3")

# Checkpoint before the risky step
snapshot = vm.snapshot(snapshot_id="before-experiment")
vm.close()

# Restore and try the experiment
vm = SmolVM.from_snapshot("before-experiment", resume_vm=True)
result = vm.run("python3 -c 'import this_will_fail'")

if not result.ok:
    print("Experiment failed — rolling back")
    vm.stop()
    vm.delete()

    # Restore from checkpoint and try a different approach
    vm = SmolVM.from_snapshot("before-experiment", resume_vm=True, force=True)
    result = vm.run("python3 -c 'print(42)'")
    print(result.output)  # 42

vm.close()

​
Snapshot ID rules

Snapshot IDs must contain only lowercase letters, numbers, hyphens, and underscores. SmolVM validates this on creation and raises an error for invalid IDs. Valid examples: my-checkpoint, snap-agent-001, pre-deploy-v2

​
Error handling

SmolVM provides specific exceptions for snapshot operations: 
from smolvm import (
    SmolVM,
    SnapshotAlreadyExistsError,
    SnapshotNotFoundError,
    SnapshotType,
    SmolVMError,
)

try:
    snapshot = vm.snapshot(snapshot_id="my-checkpoint")
except SnapshotAlreadyExistsError:
    print("A snapshot with this ID already exists")
except SmolVMError as e:
    print(f"Snapshot failed: {e.message}")

try:
    vm = SmolVM.from_snapshot("missing-snapshot")
except SnapshotNotFoundError:
    print("Snapshot not found")

​
Next steps

Snapshot CLI reference

Full list of snapshot CLI commands and options

SnapshotInfo API

Snapshot metadata returned by the SDK

VM lifecycle

Understand the full sandbox lifecycle

AI agent integration

Build secure agent sandboxes with checkpointing
Last modified on June 6, 2026