> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-toks-cloud-snapshot-contracts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Python SDK - Snapshot API reference

Capture the disk state of a stopped sandbox through the active backend, then
boot fresh sandboxes from it. Local snapshots are reusable artifacts; cloud
snapshots use managed storage or the organization's host volume. Snapshots are
disk-only and require a sandbox that is not running.

<Note>
  `list_dir`, `reindex`, `save`/`save_to`, `load`, and `verify` keep the same
  API on every backend, but currently raise `UnsupportedError` in cloud.
</Note>

## Take a snapshot

#### <span className="msb-recv">handle.</span><span className="msb-hn">snapshot()</span>

```python theme={null}
async def snapshot(self, name: str) -> Snapshot
```

Snapshot this sandbox under a bare name. Local uses its default snapshot
directory; cloud uses managed storage. The sandbox must be stopped or crashed.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Snapshot name. Local stores it in the default snapshot directory; cloud creates a managed snapshot.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot">Snapshot</a></div>
    <div className="msb-param-desc">The captured snapshot.</div>
  </div>
</div>

<Accordion title="Example">
  ```python theme={null}
  handle = await Sandbox.get("baseline")
  snap = await handle.snapshot("after-pip-install")
  print(snap.digest)
  ```
</Accordion>

***

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">create()</span>

```python theme={null}
@staticmethod
async def create(
    name: str,
    *,
    from_sandbox: str,
    dest_dir: str | os.PathLike[str] | None = None,
    labels: dict[str, str] | None = None,
    force: bool = False,
    record_integrity: bool = False,
    resumable: bool = False,
) -> Snapshot
```

Create a snapshot from a stopped or crashed sandbox. With no `dest_dir`, local
uses its default snapshot directory and cloud uses managed storage. A
`dest_dir` selects a local parent or cloud host-volume directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Snapshot name. Its storage location is selected by the active backend.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>from\_sandbox</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Name of the stopped or crashed sandbox to capture. Required.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dest\_dir</code><span className="msb-type">str | os.PathLike\[str] | None</span></div>
    <div className="msb-param-desc">Local parent or cloud host-volume directory. Omit for backend-managed storage.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>labels</code><span className="msb-type">dict\[str, str] | None</span></div>
    <div className="msb-param-desc">User-supplied labels stored in the manifest.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Overwrite an existing artifact with the same name. Default <code>False</code>.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>record\_integrity</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Record an integrity hash in the manifest so the artifact can be verified later. Default <code>False</code>.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>resumable</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Request a <code>"resumable"</code> snapshot (disk plus VM state). Accepted, but currently fails with an <code>Unsupported</code> error; resumable snapshots have not landed yet. Default <code>False</code>.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot">Snapshot</a></div>
    <div className="msb-param-desc">The captured snapshot.</div>
  </div>
</div>

<Accordion title="Example">
  ```python theme={null}
  snap = await Snapshot.create(
      "after-pip-install",
      from_sandbox="baseline",
      labels={"stage": "post-deps"},
      record_integrity=True,
  )
  ```
</Accordion>

***

## Boot from a snapshot

#### <span className="msb-recv">Sandbox.</span><span className="msb-hn">create()</span>

```python theme={null}
@staticmethod
async def create(
    name: str,
    *,
    from_snapshot: str | os.PathLike | Snapshot | SnapshotHandle | None = None,
    **kwargs,
) -> Sandbox
```

Boot a fresh sandbox from a snapshot by passing `from_snapshot=` as a peer of
`image=`. The two are mutually exclusive. Passing a `Snapshot` or
`SnapshotHandle` preserves its backend-relative reference automatically.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Sandbox name, up to 128 UTF-8 bytes.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>from\_snapshot</code><span className="msb-type">str | os.PathLike | Snapshot | SnapshotHandle | None</span></div>
    <div className="msb-param-desc">Backend-relative string, path, or snapshot object to boot from instead of <code>image=</code>.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="/sdk/python/sandbox#instance-methods">Sandbox</a></div>
    <div className="msb-param-desc">Running sandbox.</div>
  </div>
</div>

<Accordion title="Example">
  ```python theme={null}
  # Boot from a snapshot
  sb = await Sandbox.create("worker", from_snapshot="after-pip-install")

  # Or from an image (existing flow, unchanged)
  sb = await Sandbox.create("worker", image="python:3.12")
  ```
</Accordion>

***

## Manage artifacts

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">open()</span>

```python theme={null}
@staticmethod
async def open(path_or_name: str) -> Snapshot
```

<Accordion title="Example">
  ```python theme={null}
  snap = await Snapshot.open("after-pip-install")
  print(snap.image_ref)
  ```
</Accordion>

Open an existing snapshot through the active backend. Locally, bare names
resolve under the default snapshot directory and other values are artifact
paths. In cloud, bare values identify managed snapshots and path-like values
identify host-volume artifacts. Cheap metadata validation only; use
[`verify()`](#snap-verify) for content checks where supported.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path\_or\_name</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Backend-relative snapshot name, ID, or path.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot">Snapshot</a></div>
    <div className="msb-param-desc">The opened snapshot.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">get()</span>

```python theme={null}
@staticmethod
async def get(name_or_digest: str) -> SnapshotHandle
```

<Accordion title="Example">
  ```python theme={null}
  h = await Snapshot.get("after-pip-install")
  print(h.digest)
  ```
</Accordion>

Look up a lightweight snapshot handle through the active backend.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name\_or\_digest</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Public identifier understood by the active backend, such as a local name/digest or cloud snapshot ID.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandle">SnapshotHandle</a></div>
    <div className="msb-param-desc">Lightweight handle returned by the active backend.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">list()</span>

```python theme={null}
@staticmethod
async def list() -> list[SnapshotHandle]
```

<Accordion title="Example">
  ```python theme={null}
  for h in await Snapshot.list():
      print(h.name, h.digest)
  ```
</Accordion>

List snapshots visible through the active backend. Local uses its index; cloud
lists managed snapshots. Host-volume artifacts are opened explicitly by
reference.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandle">list\[SnapshotHandle]</a></div>
    <div className="msb-param-desc">Indexed snapshot handles.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">list\_dir()</span>

```python theme={null}
@staticmethod
async def list_dir(dir: str | os.PathLike) -> list[Snapshot]
```

Walk a local directory and parse each subdirectory's manifest. Does not touch
the local index, useful for inspecting external snapshot collections. Skips
entries that don't look like snapshot artifacts. Cloud raises
`UnsupportedError`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>dir</code><span className="msb-type">str | os.PathLike</span></div>
    <div className="msb-param-desc">Directory to scan for artifacts.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot">list\[Snapshot]</a></div>
    <div className="msb-param-desc">One snapshot per valid artifact directory.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">remove()</span>

```python theme={null}
@staticmethod
async def remove(path_or_name: str, *, force: bool = False) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await Snapshot.remove("after-pip-install", force=True)
  ```
</Accordion>

Remove a snapshot through the active backend. Locally, removal also updates
the index and refuses indexed children unless `force=True`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path\_or\_name</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Bare snapshot name or artifact path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Remove even if the snapshot has indexed children. Default <code>False</code>.</div>
  </div>
</div>

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">reindex()</span>

```python theme={null}
@staticmethod
async def reindex(dir: str | os.PathLike | None = None) -> int
```

<Accordion title="Example">
  ```python theme={null}
  count = await Snapshot.reindex()
  print(f"indexed {count} snapshots")
  ```
</Accordion>

Walk `dir` (default: configured snapshots dir) and rebuild the local index.
Returns the number of artifacts indexed. Cloud raises `UnsupportedError`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>dir</code><span className="msb-type">str | os.PathLike | None</span></div>
    <div className="msb-param-desc">Directory to scan. Default: the configured snapshots directory.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">int</span></div>
    <div className="msb-param-desc">Number of artifacts indexed.</div>
  </div>
</div>

***

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">save()</span>

<div className="msb-tags"><span className="msb-tag is-static">static</span><span className="msb-tag is-async">async</span></div>

```python theme={null}
@staticmethod
async def save(
    name_or_path: str,
    out: str | os.PathLike,
    *,
    with_parents: bool = False,
    with_image: bool = False,
    plain_tar: bool = False,
) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await Snapshot.save(
      "after-pip-install",
      "/tmp/after-pip-install.tar.zst",
      with_parents=True,
  )
  ```
</Accordion>

Bundle a local snapshot into a `.tar.zst` archive. The existing snapshot
manifest is archived as-is; create the snapshot with recorded integrity when
the archive will cross a trust boundary. Cloud raises `UnsupportedError`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name\_or\_path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Snapshot bare name or artifact path to save.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>out</code><span className="msb-type">str | os.PathLike</span></div>
    <div className="msb-param-desc">Output archive path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_parents</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Include the snapshot's parent chain. Default <code>False</code>.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_image</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Include the pinned base image. Default <code>False</code>.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>plain\_tar</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Write an uncompressed <code>.tar</code> instead of <code>.tar.zst</code>. Default <code>False</code>.</div>
  </div>
</div>

***

## Move artifacts

***

#### <span className="msb-recv">Snapshot.</span><span className="msb-hn">load()</span>

<div className="msb-tags"><span className="msb-tag is-static">static</span><span className="msb-tag is-async">async</span></div>

```python theme={null}
@staticmethod
async def load(
    archive: str | os.PathLike,
    *,
    dest: str | os.PathLike | None = None,
) -> SnapshotHandle
```

Unpack a snapshot archive (`.tar.zst` or `.tar`) into the local snapshots
directory. Structural and archive-entry checks run during import; recorded
payload integrity is preserved for explicit [`verify()`](#snap-verify).
Compression is detected from magic bytes. Cloud raises `UnsupportedError`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>archive</code><span className="msb-type">str | os.PathLike</span></div>
    <div className="msb-param-desc">Archive path (<code>.tar.zst</code> or <code>.tar</code>).</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dest</code><span className="msb-type">str | os.PathLike | None</span></div>
    <div className="msb-param-desc">Destination directory. Default: the configured snapshots directory.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshothandle">SnapshotHandle</a></div>
    <div className="msb-param-desc">Handle to the loaded snapshot.</div>
  </div>
</div>

<Accordion title="Example">
  ```python theme={null}
  h = await Snapshot.load("/tmp/after-pip-install.tar.zst")
  print(h.reference)
  ```
</Accordion>

***

## Inspect

#### <span className="msb-recv">snap.</span><span className="msb-hn">save\_to()</span>

```python theme={null}
async def save_to(
    self,
    out: str | os.PathLike,
    *,
    with_parents: bool = False,
    with_image: bool = False,
    plain_tar: bool = False,
) -> None
```

Bundle this snapshot through the backend retained when it was created or
opened. This avoids resolving its reference through a possibly different
current default backend. Cloud raises `UnsupportedError`.

```python theme={null}
await snap.save_to("/tmp/after-pip-install.tar.zst", with_image=True)
```

#### <span className="msb-recv">snap.</span><span className="msb-hn">verify()</span>

```python theme={null}
async def verify(self) -> dict[str, Any]
```

<Accordion title="Example">
  ```python theme={null}
  report = await snap.verify()
  if report["upper"]["kind"] == "verified":
      print(f"hash matches: {report['upper']['digest']}")
  else:
      print("no integrity hash recorded")
  ```
</Accordion>

Recompute the upper layer's recorded content integrity and compare against the descriptor. Current BLAKE3 Merkle integrity skips known all-hole subtrees and hashes allocated leaves in batches; released SHA descriptors retain their exact, potentially O(logical size), verifier. Returns `not_recorded` without reading payload contents when no integrity was stored. The cloud backend currently raises `UnsupportedError`.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">dict\[str, Any]</span></div>
    <div className="msb-param-desc">Verification report. The <code>upper.kind</code> field is <code>"not\_recorded"</code> when no integrity hash was stored, or <code>"verified"</code> with the recomputed digest.</div>
  </div>
</div>

The report shape:

```python theme={null}
{
    "digest": "sha256:...",
    "path": "/path/to/artifact",
    "upper": {"kind": "not_recorded"}                            # no integrity recorded
        | {"kind": "verified", "algorithm": "...", "digest": "sha256:..."},
}
```

#### <span className="msb-recv">handle.</span><span className="msb-hn">open()</span>

```python theme={null}
async def open(self) -> Snapshot
```

<Accordion title="Example">
  ```python theme={null}
  h = await Snapshot.get("after-pip-install")
  snap = await h.open()
  print(snap.fstype)
  ```
</Accordion>

Load the full [`Snapshot`](#snapshot) metadata for this handle. Metadata-validated only; does not read the upper file.

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshot">Snapshot</a></div>
    <div className="msb-param-desc">The opened snapshot.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">remove()</span>

```python theme={null}
async def remove(self, *, force: bool = False) -> None
```

<Accordion title="Example">
  ```python theme={null}
  h = await Snapshot.get("after-pip-install")
  await h.remove(force=False)
  ```
</Accordion>

Remove this snapshot artifact and its index row. Refuses if the snapshot has indexed children unless `force=True`.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">Remove even if the snapshot has indexed children. Default <code>False</code>.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">save\_to()</span>

```python theme={null}
async def save_to(
    self,
    out: str | os.PathLike,
    *,
    with_parents: bool = False,
    with_image: bool = False,
    plain_tar: bool = False,
) -> None
```

Bundle the referenced snapshot through the backend retained by the handle.
Cloud raises `UnsupportedError`.

## Types

### Snapshot

<div className="msb-tags"><span className="msb-tag is-type">class</span></div>

<p className="msb-backref">Returned by <a href="#handle-snapshot">snapshot()</a> · <a href="#snapshot-create">Snapshot.create()</a> · <a href="#snapshot-open">Snapshot.open()</a> · <a href="#snapshot-list_dir">Snapshot.list\_dir()</a> · <a href="#handle-open">handle.open()</a></p>

A fully parsed backend-neutral snapshot. Properties are read-only attributes.

| Property / Method            | Type                                          | Description                                                                        |
| ---------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------- |
| `reference`                  | `str`                                         | Stable backend-relative restore reference                                          |
| `reference_kind`             | `Literal["id", "path"]`                       | How the selected backend resolves the reference                                    |
| `digest`                     | `str`                                         | Canonical content digest (`sha256:hex`). The snapshot's identity                   |
| `size_bytes`                 | `int \| None`                                 | Backend-reported stored payload size in bytes                                      |
| `image_ref`                  | `str`                                         | Image reference the snapshot was taken from                                        |
| `image_manifest_digest`      | `str`                                         | OCI manifest digest of the pinned image                                            |
| `state_kind`                 | [`SnapshotStateKind`](#snapshotstatekind)     | File-backed or checkpoint-backed state                                             |
| `format`                     | [`SnapshotFormat`](#snapshotformat)` \| None` | On-disk format for file-backed state                                               |
| `scope`                      | [`SnapshotScope`](#snapshotscope)             | Captured state scope                                                               |
| `fstype`                     | `str \| None`                                 | Filesystem type for file-backed state (e.g. `"ext4"`)                              |
| `checkpoint_id`              | `str \| None`                                 | Checkpoint identifier for checkpoint-backed state                                  |
| `checkpoint_manifest_digest` | `str \| None`                                 | Checkpoint manifest digest for checkpoint-backed state                             |
| `parent`                     | `str \| None`                                 | Parent snapshot's digest, or `None` for a root                                     |
| `created_at`                 | `str`                                         | RFC 3339 timestamp                                                                 |
| `labels`                     | `dict[str, str]`                              | User-supplied labels                                                               |
| `source_sandbox`             | `str \| None`                                 | Best-effort source-sandbox name                                                    |
| `save_to(...)`               | `Awaitable[None]`                             | Bundle through the backend retained by this snapshot                               |
| `verify()`                   | `Awaitable[dict[str, Any]]`                   | Recompute and check the upper-layer integrity hash. See [`verify()`](#snap-verify) |

### SnapshotHandle

<div className="msb-tags"><span className="msb-tag is-type">class</span></div>

<p className="msb-backref">Returned by <a href="#snapshot-get">Snapshot.get()</a> · <a href="#snapshot-list">Snapshot.list()</a> · <a href="#snapshot-load">Snapshot.load()</a></p>

Lightweight handle returned by the active backend. Properties are read-only.

| Property / Method            | Type                                          | Description                                                             |
| ---------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
| `digest`                     | `str`                                         | Manifest digest, canonical identity                                     |
| `name`                       | `str \| None`                                 | Convenience alias                                                       |
| `parent_digest`              | `str \| None`                                 | Parent snapshot digest, or `None` for a root                            |
| `image_ref`                  | `str`                                         | Image the snapshot was taken from                                       |
| `state_kind`                 | [`SnapshotStateKind`](#snapshotstatekind)     | File-backed or checkpoint-backed state                                  |
| `format`                     | [`SnapshotFormat`](#snapshotformat)` \| None` | On-disk format for file-backed state                                    |
| `scope`                      | [`SnapshotScope`](#snapshotscope)             | Captured state scope                                                    |
| `fstype`                     | `str \| None`                                 | Filesystem type for file-backed state                                   |
| `checkpoint_manifest_digest` | `str \| None`                                 | Checkpoint manifest digest for checkpoint-backed state                  |
| `size_bytes`                 | `int \| None`                                 | Backend-reported stored payload size, when known                        |
| `locality`                   | `str`                                         | Artifact locality reported by the index                                 |
| `availability`               | `str`                                         | Artifact availability reported by the index                             |
| `migration_state`            | `str`                                         | Current migration state                                                 |
| `migration_error_code`       | `str \| None`                                 | Migration error code, when migration failed                             |
| `created_at`                 | `float`                                       | ms since Unix epoch                                                     |
| `reference`                  | `str`                                         | Stable backend-relative restore reference                               |
| `reference_kind`             | `Literal["id", "path"]`                       | How the selected backend resolves the reference                         |
| `open()`                     | `Awaitable[`[`Snapshot`](#snapshot)`]`        | Load full metadata. See [`open()`](#handle-open)                        |
| `remove(force=False)`        | `Awaitable[None]`                             | Delete the artifact and its index row. See [`remove()`](#handle-remove) |
| `save_to(...)`               | `Awaitable[None]`                             | Bundle through the backend retained by this handle                      |

### SnapshotStateKind

<p className="msb-backref">Returned by <a href="#snapshot">Snapshot.state\_kind</a> · <a href="#snapshothandle">SnapshotHandle.state\_kind</a></p>

Snapshot state representation.

| Member                         | Value          | Description                      |
| ------------------------------ | -------------- | -------------------------------- |
| `SnapshotStateKind.FILE`       | `"file"`       | File-backed upper-layer state    |
| `SnapshotStateKind.CHECKPOINT` | `"checkpoint"` | Checkpoint-manifest-backed state |

### SnapshotFormat

<p className="msb-backref">Returned by <a href="#snapshot">Snapshot.format</a> · <a href="#snapshothandle">SnapshotHandle.format</a></p>

On-disk format for file-backed snapshot state.

| Member                 | Value     | Description                 |
| ---------------------- | --------- | --------------------------- |
| `SnapshotFormat.RAW`   | `"raw"`   | Raw disk image              |
| `SnapshotFormat.QCOW2` | `"qcow2"` | QEMU copy-on-write v2 image |

### SnapshotScope

<p className="msb-backref">Returned by <a href="#snapshot">Snapshot.scope</a> · <a href="#snapshothandle">SnapshotHandle.scope</a></p>

Captured snapshot state scope.

| Member                    | Value         | Description                    |
| ------------------------- | ------------- | ------------------------------ |
| `SnapshotScope.DISK`      | `"disk"`      | Disk-only state                |
| `SnapshotScope.RESUMABLE` | `"resumable"` | Disk, memory, and device state |

```python theme={null}
from microsandbox import SnapshotFormat, SnapshotScope, SnapshotStateKind

assert snapshot.state_kind is SnapshotStateKind.FILE
assert snapshot.format is SnapshotFormat.RAW
assert snapshot.scope is SnapshotScope.DISK
```