> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# smolvm sandbox snapshot

> Use smolvm sandbox snapshot to save, restore, list, and delete sandbox checkpoints for retries, handoffs, and long-running agent workflows.

`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

```bash theme={null}
smolvm sandbox snapshot create <sandbox> [OPTIONS]
smolvm sandbox snapshot restore <snapshot> [OPTIONS]
smolvm sandbox snapshot list [OPTIONS]
smolvm sandbox snapshot delete <snapshot> [OPTIONS]
```

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

## create

Save a running or paused sandbox.

```bash theme={null}
smolvm sandbox snapshot create <sandbox> \
  [--snapshot-id <id>] \
  [--snapshot-type full|diff|disk] \
  [--resume-source] \
  [--json]
```

<ParamField path="sandbox" type="string" required>
  Name or ID of the sandbox to snapshot.
</ParamField>

<ParamField path="--snapshot-id" type="string">
  Custom snapshot ID. If omitted, SmolVM creates one.
</ParamField>

<ParamField path="--snapshot-type" 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.
</ParamField>

<ParamField path="--resume-source" type="flag">
  Resume the source sandbox after the snapshot is created.
</ParamField>

```bash theme={null}
smolvm sandbox snapshot create my-sandbox \
  --snapshot-id before-deploy \
  --resume-source
```

Create a QEMU disk-only snapshot:

```bash theme={null}
smolvm sandbox snapshot create my-sandbox --snapshot-type disk
```

## restore

Restore a snapshot back into its sandbox identity.

```bash theme={null}
smolvm sandbox snapshot restore <snapshot> [--resume] [--force] [--json]
```

<ParamField path="snapshot" type="string" required>
  Snapshot ID to restore.
</ParamField>

<ParamField path="--resume" type="flag">
  Resume the restored sandbox immediately.
</ParamField>

<ParamField path="--force" type="flag">
  Restore a snapshot even if SmolVM has already marked it restored.
</ParamField>

```bash theme={null}
smolvm sandbox snapshot restore before-deploy --resume
```

## list

List snapshots, optionally filtered by source sandbox.

```bash theme={null}
smolvm sandbox snapshot list [--vm-id <sandbox>] [--json]
```

```bash theme={null}
smolvm sandbox snapshot list --vm-id my-sandbox
```

## delete

Delete a snapshot and its files.

```bash theme={null}
smolvm sandbox snapshot delete <snapshot> [--json]
```

<Warning>
  Deleting a snapshot removes its saved disk, memory, and state files.
</Warning>

## 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](/smolvm/concepts/control-channel) and [Troubleshooting](/smolvm/advanced/troubleshooting) before debugging storage or upload paths.

## Related commands

* [`smolvm sandbox list`](/smolvm/cli/list) - Find sandbox names
* [`smolvm sandbox shell`](/smolvm/cli/shell) - Inspect a restored sandbox
* [Snapshot and restore sandboxes](/smolvm/features/snapshots) - Learn when to use each snapshot type