Skip to main content
Snapshots let you freeze a running sandbox and bring it back exactly where you left off. This is useful when you want to save a configured environment, retry a failed step, or checkpoint an agent’s progress before a risky operation. A snapshot captures the full state of the VM: CPU registers, memory contents, and the root filesystem disk. When you restore a snapshot, the sandbox boots into the exact same state it was in when the snapshot was created.
Snapshots are available on the Firecracker backend (Linux only). The QEMU backend does not currently support SmolVM snapshots.

​
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).

​
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. The saved VM state, memory dump, and disk copy are removed and cannot be recovered.

​
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, and hyphens. 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,
    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 April 3, 2026