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

# Snapshot commands

> Capture, inspect, restore, and move snapshots from the CLI

<Tooltip tip="Cloud supports disk capture from stopped or crashed sandboxes, listing, inspection, removal, and restore. Full snapshots, groups, archives, and verification are local-only."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

Manage saved snapshots with `msb snapshot` (alias: `msb snap`). See the [snapshot guide](/sandboxes/snapshots) for workflows.

Local selectors accept a group head, `group:member`, an unambiguous ID or digest, or an artifact path. On cloud, use the snapshot reference returned by the command.

## msb snapshot create

Capture disk state. Add `--full` to include memory and running processes.

```bash theme={null}
msb snapshot create ready --from-sandbox worker
```

| Argument / flag       | Description                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `NAME`                | Member name; generated when omitted                                                       |
| `--from-sandbox NAME` | Required source sandbox                                                                   |
| `--group GROUP`       | Local group; defaults to the source sandbox’s name                                        |
| `--dest-dir DIR`      | Parent directory for local groups                                                         |
| `-o`, `--output PATH` | Capture directly to an archive; conflicts with `--dest-dir` and does not accept `--group` |
| `--full`              | Capture disk, memory, and execution state from a running or paused source                 |
| `--integrity`         | Record content hashes for later verification                                              |
| `--label KEY=VALUE`   | Attach a label; repeatable                                                                |
| `--plain-tar`         | Write uncompressed tar; requires `--output`                                               |
| `-f`, `--force`       | Overwrite an archive output; not allowed for installed members                            |
| `-q`, `--quiet`       | Suppress output                                                                           |

Local disk capture accepts running, paused, stopped, or crashed sources. Stop first to include buffered writes. Cloud requires a stopped or crashed source.

<Accordion title="Examples">
  ```bash theme={null}
  msb snapshot create snap --from-sandbox worker --full
  msb snapshot create ready --from-sandbox worker --integrity
  msb snapshot create ready --from-sandbox worker -o ready.msb
  ```
</Accordion>

## msb snapshot list

List snapshots. Aliases: `msb snapshot ls`, `msb snapshots`, and `msb snaps`.

```bash theme={null}
msb snapshots
```

| Flag            | Description       |
| --------------- | ----------------- |
| `--format json` | JSON output       |
| `-q`, `--quiet` | Show only digests |

## msb snapshot inspect

Show snapshot metadata. Add `--verify` to check recorded content hashes.

```bash theme={null}
msb snapshot inspect worker:ready
msb snapshot inspect worker:ready --verify
```

## msb snapshot verify

Check recorded content integrity. Local-only; capture with `--integrity` to record disk hashes.

```bash theme={null}
msb snapshot verify worker:ready
```

Without disk hashes, size and structure checks cannot detect same-size corruption. Full snapshots also validate their memory and execution objects. See [integrity](/sandboxes/snapshots#verify-integrity).

## msb snapshot remove

Delete one or more snapshots. Alias: `msb snapshot rm`.

```bash theme={null}
msb snapshot rm worker:ready
```

| Flag            | Description                             |
| --------------- | --------------------------------------- |
| `-f`, `--force` | Remove even when indexed children exist |
| `-q`, `--quiet` | Suppress output                         |

If other group members remain, select another head before removing the current one. `--force` does not bypass this rule.

## msb snapshot head

Read a local group’s head, or select a member as its head.

```bash theme={null}
msb snapshot head worker
msb snapshot head worker:ready
```

Use `--format json` for structured output. The first capture sets the head; later captures advance it only when ancestry proves they descend from it. See [snapshot groups](/sandboxes/snapshots#snapshot-groups).

## msb snapshot save

Export a local snapshot to a compressed `.msb` archive.

```bash theme={null}
msb snapshot save worker:ready ready.msb --with-image
```

| Flag              | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `--with-image`    | Bundle the OCI image for offline restore                                          |
| `--with-parents`  | Include the parent chain                                                          |
| `--plain-tar`     | Write uncompressed tar                                                            |
| `--since BASE`    | Omit disk layers and RAM objects supplied by an exact base                        |
| `--last-layers N` | Export the newest N sealed root-disk layers; the omitted base is needed on import |

`--since`, `--last-layers`, and `--with-parents` are mutually exclusive. Export preserves recorded hashes but does not verify them. See [incremental exports](/sandboxes/snapshots#export-changes) for base requirements.

## msb snapshot load

Import one or more local archives. Dependencies resolve regardless of input order; all members are validated before publication.

```bash theme={null}
msb snapshot load ready.msb
```

| Flag              | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `--dest DIR`      | Parent directory for groups; defaults to the configured snapshot store      |
| `--group GROUP`   | Destination group; generated when omitted                                   |
| `--base SNAPSHOT` | External snapshot or standalone archive for missing dependencies            |
| `--set-head`      | Select the imported tip even with divergent ancestry; requires a unique tip |

Dependencies come from the batch, matching members in the named group, or `--base`. Import preserves recorded hashes; run `verify` to check them.

<Accordion title="Examples">
  ```bash theme={null}
  msb snapshot load changes.msb base.msb --group received
  msb snapshot load changes.msb --base worker:ready --group received
  msb snapshot load experiment.msb --group worker --set-head
  ```
</Accordion>

## msb snapshot reindex

Rebuild the local snapshot index from artifacts on disk. An omitted directory uses the configured snapshot store.

```bash theme={null}
msb snapshot reindex
msb snapshot reindex /mnt/snapshots
```

## Related commands

| Command                                                    | Purpose                                          |
| ---------------------------------------------------------- | ------------------------------------------------ |
| [`msb restore`](/cli/sandbox-commands#msb-restore)         | Restore a snapshot into a new sandbox            |
| [`msb branch`](/cli/sandbox-commands#msb-sandbox-branch)   | Copy running execution without saving a snapshot |
| [`msb modify --compact`](/cli/sandbox-commands#compaction) | Merge sealed disk layers                         |