> ## 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] \
  [--live-only] \
  [--flush-policy required|best-effort|skip] \
  [--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>

<ParamField path="--live-only" type="flag">
  Keep a running QEMU sandbox available for the whole snapshot instead of briefly pausing it. Requires `--snapshot-type disk` and `--resume-source`, and only works on QEMU. If the installed QEMU cannot do a live block backup, the command fails rather than falling back to a pause.
</ParamField>

<ParamField path="--flush-policy" type="string" default="required">
  How to handle the pre-snapshot guest filesystem flush for `--snapshot-type disk`. `required` fails the snapshot if the flush fails, `best-effort` continues with a crash-consistent copy, and `skip` does not ask the guest to flush at all.
</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
```

Take a live disk snapshot of a running QEMU sandbox without pausing the guest:

```bash theme={null}
smolvm sandbox snapshot create my-sandbox \
  --snapshot-id live-checkpoint \
  --snapshot-type disk \
  --resume-source \
  --live-only
```

Use `--flush-policy` to trade durability for speed. This example keeps a sandbox running through a live snapshot and doesn't fail if the guest agent can't flush:

```bash theme={null}
smolvm sandbox snapshot create my-sandbox \
  --snapshot-type disk \
  --resume-source \
  --live-only \
  --flush-policy best-effort
```

## 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.

Use `--flush-policy` to tune this step: `required` (default) fails the snapshot if the flush cannot succeed, `best-effort` continues with a crash-consistent copy, and `skip` bypasses the flush entirely.

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