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

# Snapshots

> Create and restore sandbox snapshots with the TypeScript SDK.

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

See the [snapshot guide](/sandboxes/snapshots) for workflows and examples.

Use snapshot objects or references on cloud. Local operations also accept a group head, `group:member`, or artifact path.

## Guest writeback

Use `.guestFlush("required")` on snapshot builders or `{ guestFlush: "required" }` in `source.fork`, `source.forkMany`, and `source.pause` options. The default `"auto"` flushes live disk-only captures, but adds no optional flush to full captures, forks, or pause. `"skip"` retains mandatory storage barriers. A paused disk capture needs a matching prior flush; cloud rejects non-Auto policies. See [guest flush policy reference](/sandboxes/snapshots#guest-flushing).

## Snapshot

A snapshot retains the backend that created or opened it.

<p className="msb-member-group">Static methods</p>

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

```typescript theme={null}
static builder(name?: string): SnapshotBuilder
```

Configure a snapshot. Set the required source with `fromSandbox()`; see [SnapshotBuilder](#snapshotbuilder) for options.

<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">string</span></div>
    <div className="msb-param-desc">Member name within its group; generated when omitted.</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="#snapshotbuilder">SnapshotBuilder</a></div>
    <div className="msb-param-desc">Builder for configuring the snapshot.</div>
  </div>
</div>

<Accordion title="Example">
  ```typescript theme={null}
  const snap = await Snapshot.builder("deps")
    .fromSandbox("baseline")
    .label("stage", "post-deps")
    .recordIntegrity()
    .create();
  ```
</Accordion>

***

#### <span className="msb-recv">builder.</span><span className="msb-hn">createArchive()</span>

```typescript theme={null}
createArchive(out: string, plainTar?: boolean): Promise<SnapshotArchive>
```

Capture directly into an archive without installing a local snapshot.

<Accordion title="Example">
  ```typescript theme={null}
  const archive = await Snapshot.builder("deps")
    .fromSandbox("baseline")
    .createArchive("/tmp/deps.msb");
  ```
</Accordion>

***

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

```typescript theme={null}
static open(pathOrName: string): Promise<Snapshot>
```

<Accordion title="Example">
  ```typescript theme={null}
  const snap = await Snapshot.open("baseline:deps");
  console.log(snap.digest);
  ```
</Accordion>

Open an existing snapshot artifact by group head, `group:member`, or path. Cheap metadata validation only; it does not read the upper file. Use [`verify()`](#snap-verify) for content checks.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Group head or <code>group:member</code> selector or filesystem 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">Promise\<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>

```typescript theme={null}
static get(nameOrDigest: string): Promise<SnapshotHandle>
```

<Accordion title="Example">
  ```typescript theme={null}
  const h = await Snapshot.get("baseline:deps");
  console.log(h.digest, h.createdAt);
  ```
</Accordion>

Look up a snapshot through the active backend and return a lightweight
[`SnapshotHandle`](#snapshothandle).

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>nameOrDigest</code><span className="msb-type">string</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">Promise\<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>

```typescript theme={null}
static list(): Promise<SnapshotHandle[]>
```

<Accordion title="Example">
  ```typescript theme={null}
  for (const h of await Snapshot.list()) {
    console.log(h.name ?? h.digest, h.sizeBytes);
  }
  ```
</Accordion>

List snapshots visible through the active backend. 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">Promise\<SnapshotHandle\[]></a></div>
    <div className="msb-param-desc">All indexed snapshot handles.</div>
  </div>
</div>

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

```typescript theme={null}
static listDir(dir: string): Promise<Snapshot[]>
```

Walk a local directory and parse each subdirectory's manifest. Does not touch
the local index, which makes it useful for inspecting external snapshot
collections that were never loaded. Skips entries that don't look like
snapshot artifacts. Cloud returns `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">string</span></div>
    <div className="msb-param-desc">Directory to scan for artifact subdirectories.</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">Promise\<Snapshot\[]></a></div>
    <div className="msb-param-desc">Parsed snapshots found in the directory.</div>
  </div>
</div>

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

```typescript theme={null}
static remove(pathOrName: string, opts?: { force?: boolean }): Promise<void>
```

<Accordion title="Example">
  ```typescript theme={null}
  await Snapshot.remove("baseline:deps", { force: true });
  ```
</Accordion>

Remove a snapshot by group selector, unambiguous ID or digest, or path. Refuses if the snapshot has indexed children unless `force` is set. A group's head cannot be removed while other members remain, even with `force`; select another head first.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>pathOrName</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Group head, <code>group:member</code>, unambiguous snapshot ID or digest, or artifact path.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>opts.force</code><span className="msb-type">boolean</span></div>
    <div className="msb-param-desc">Remove even if the snapshot has indexed children. Defaults to <code>false</code>.</div>
  </div>
</div>

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

```typescript theme={null}
static reindex(dir?: string): Promise<number>
```

<Accordion title="Example">
  ```typescript theme={null}
  const count = await Snapshot.reindex();
  console.log(`reindexed ${count} snapshots`);
  ```
</Accordion>

Walk a local snapshots directory (default: the configured snapshots dir) and
rebuild the local index. Returns the number of artifacts indexed. Cloud
returns `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">string</span></div>
    <div className="msb-param-desc">Directory to scan. Defaults to the configured snapshots dir.</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">Promise\<number></span></div>
    <div className="msb-param-desc">Count 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>

```typescript theme={null}
static save(nameOrPath: string, out: string, opts?: SaveOpts): Promise<void>
```

Bundle a snapshot into a `.msb` archive. The recorded manifest is archived as-is, so create the snapshot with [`recordIntegrity()`](#recordintegrity) if receivers must verify content. See [`SaveOpts`](#saveopts-interface) for bundling options.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>nameOrPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Group head, <code>group:member</code>, or artifact path to bundle.</div>
  </div>

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

  <div className="msb-param">
    <div className="msb-param-key"><code>opts</code><a className="msb-type" href="#saveopts-interface">SaveOpts</a></div>
    <div className="msb-param-desc">Bundling options. All fields default to <code>false</code>.</div>
  </div>
</div>

<Accordion title="Example">
  ```typescript theme={null}
  await Snapshot.save("baseline:deps", "./baseline.msb", {
    withImage: true,
  });
  ```
</Accordion>

***

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

```typescript theme={null}
static load(archive: string, dest?: string, base?: string): Promise<SnapshotHandle>
```

Unpack a snapshot archive (`.msb` or `.tar`) into the 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.

<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">string</span></div>
    <div className="msb-param-desc">Path to the archive to unpack.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dest</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Destination directory. Defaults to the 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">Promise\<SnapshotHandle></a></div>
    <div className="msb-param-desc">Handle to the loaded snapshot.</div>
  </div>
</div>

<Accordion title="Example">
  ```typescript theme={null}
  const h = await Snapshot.load("./baseline.msb");
  console.log("loaded", h.digest);
  ```
</Accordion>

***

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

```typescript theme={null}
static loadWithOptions(archive: string, opts?: LoadOpts): Promise<SnapshotHandle>
```

Import an archive with an explicit dependency base or destination group. See [import options](#import-options).

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

```typescript theme={null}
static loadMany(archives: string[], opts?: LoadOpts): Promise<SnapshotHandle[]>
```

Import archives as one batch. Returns handles in input order. Dependencies resolve from the batch, the named group, or an explicit base; input order does not matter. All members are validated before publication.

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

```typescript theme={null}
static groupHead(selector: string): Promise<HeadUpdate>
```

Read a group’s head, or select an exact member with `group:member`. Returns the group, previous and current snapshot IDs, reason, and whether the head changed. See [group selection](/sandboxes/snapshots#snapshot-groups).

<span id="snapshot-groups" />

<span id="load-multiple-archives" />

### Import options

Options for `LoadOpts`.

| Option | Purpose |
| - | - |
| `dest` | Parent directory containing groups. Defaults to the local snapshot store. |
| `base` | External snapshot or standalone archive for missing dependencies. |
| `group` | Destination group. Omit to create one group for the import. |
| `setHead` | Select the imported tip, even with divergent ancestry. Defaults to false; requires a unique tip. |

With divergent tips, the existing head stays selected; a new group has no head. Select a member explicitly. Identical members may be reused; conflicting identities fail. See [archive imports](/sandboxes/snapshots#import-archives).

## SandboxHandle

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

```typescript theme={null}
snapshot(name: string): Promise<Snapshot>
```

Snapshot this sandbox into its default group with the given member name. Called on a [`SandboxHandle`](/sdk/typescript/sandbox#sandboxhandle). Local live disk captures preserve the source's running or paused state. Cloud requires a stopped persistent source. Use the returned artifact path or `sandbox:member` to open it later.

<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">string</span></div>
    <div className="msb-param-desc">Member name within the source sandbox's group.</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">Promise\<Snapshot></a></div>
    <div className="msb-param-desc">The created snapshot artifact.</div>
  </div>
</div>

<Accordion title="Example">
  ```typescript theme={null}
  const h = await Sandbox.get("baseline");
  await h.stop();
  const snap = await h.snapshot("deps");
  ```
</Accordion>

***

<h2 id="snapshot-instance">
  Snapshot instance members
</h2>

A `Snapshot` represents a backend-neutral snapshot and retains the backend
that created or opened it. Returned by [`Snapshot.builder().create()`](#snapshotbuilder),
[`Snapshot.open()`](#snapshot-open), and [`handle.snapshot()`](#handle-snapshot).

| Field | Type | Description |
| - | - | - |
| <span id="snap-id" />`id` | `string` | Stable opaque `snap_...` identity, separate from the descriptor digest. |
| <span id="snap-path" />`path` | `string` | Local artifact directory. Throws `UnsupportedError` for cloud snapshots; use the snapshot object or its typed reference for backend-neutral operations. |
| <span id="snap-reference" />`reference` | `string` | Stable backend-relative value. Pass the snapshot object to `Sandbox.restore(snapshot)` to preserve both this value and its reference kind. |
| <span id="snap-referencekind" />`referenceKind` | `"id" \| "path"` | How the selected backend resolves `reference`. Most callers can pass the snapshot object directly and never inspect this value. |
| <span id="snap-digest" />`digest` | `string` | Canonical descriptor digest (`sha256:hex`), separate from the stable snapshot ID. |
| <span id="snap-sizebytes" />`sizeBytes` | `bigint \| null` | Backend-reported stored payload size in bytes, or `null` when unavailable. |
| <span id="snap-imageref" />`imageRef` | `string` | Image reference the snapshot was taken from. |
| <span id="snap-imagemanifestdigest" />`imageManifestDigest` | `string` | OCI manifest digest of the pinned image. |
| <span id="snap-format" />`format` | `"raw" \| "qcow2" \| null` | On-disk format of the upper layer. |
| <span id="snap-scope" />`scope` | `SnapshotScope` | Snapshot scope: `"disk"` for a disk-only snapshot or `"full"` for disk plus VM execution state. See [`SnapshotScope`](#snapshotscope-type). |
| <span id="snap-fstype" />`fstype` | `string \| null` | Filesystem type inside the upper (e.g. `"ext4"`). |
| <span id="snap-parent" />`parent` | `string \| null` | Manifest digest of the parent snapshot, or `null` for a root. |
| <span id="snap-createdat" />`createdAt` | `string` | RFC 3339 timestamp when the snapshot was created. |
| <span id="snap-labels" />`labels` | `ReadonlyArray<readonly [string, string]>` | User-supplied labels (sorted by key in canonical form), as `[key, value]` pairs. |
| <span id="snap-sourcesandbox" />`sourceSandbox` | `string \| null` | Best-effort source-sandbox name, if recorded. `null` when the manifest has no source recorded. |

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

```typescript theme={null}
saveTo(out: string, opts?: SaveOpts): Promise<void>
```

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

<Accordion title="Example">
  ```typescript theme={null}
  await snap.saveTo("./baseline.tar.zst", { withImage: true });
  ```
</Accordion>

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

```typescript theme={null}
copyTo(outputArchivePath: string): SnapshotCopyBuilder
```

Create a new archive from this snapshot's disk data while replacing its labels
and integrity metadata. The source snapshot is unchanged. Cloud returns
`UnsupportedError` when `save()` is awaited.

<Accordion title="Example">
  ```typescript theme={null}
  await snap
    .copyTo("./baseline-copy.tar.zst")
    .labels({ environment: "test" })
    .recordIntegrity(true)
    .save();
  ```
</Accordion>

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

```typescript theme={null}
verify(): Promise<SnapshotVerifyReport>
```

<Accordion title="Example">
  ```typescript theme={null}
  const report = await snap.verify();
  if (report.upper.kind === "verified") {
    console.log(`hash matches: ${report.upper.digest}`);
  } else {
    console.log("no integrity hash recorded");
  }
  ```
</Accordion>

Verify the snapshot's complete state closure. File state recomputes recorded upper-layer integrity. Checkpoint state validates the complete checkpoint closure and returns its root in `report.checkpoint`.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#snapshotverifyreport-union">Promise\<SnapshotVerifyReport></a></div>
    <div className="msb-param-desc">Verification result.</div>
  </div>
</div>

## SnapshotHandle

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

A metadata and lifecycle handle for an existing snapshot.

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

| Field | Type | Description |
| - | - | - |
| <span id="snapshothandle-digest" />`digest` | `string` | Descriptor digest (`sha256:hex`), separate from the stable snapshot ID. |
| <span id="snapshothandle-name" />`name` | `string \| null` | Member name within its group, or `null` when no alias is recorded. |
| <span id="snapshothandle-parentdigest" />`parentDigest` | `string \| null` | Parent snapshot's manifest digest, or `null` for a root. |
| <span id="snapshothandle-scope" />`scope` | [`SnapshotScope`](#snapshotscope-type) | Snapshot payload scope (`"disk"` today). |
| <span id="snapshothandle-imageref" />`imageRef` | `string` | Image reference the snapshot was taken from. |
| <span id="snapshothandle-format" />`format` | `"raw" \| "qcow2"` | On-disk format of the upper layer. |
| <span id="snapshothandle-sizebytes" />`sizeBytes` | `bigint \| null` | Apparent size of the upper file at index time. |
| <span id="snapshothandle-createdat" />`createdAt` | `Date` | Snapshot creation time (from manifest). |
| <span id="snapshothandle-path" />`path` | `string` | Local artifact directory path. |

<h4 id="snapshothandleopen">
  <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">open()</span>
</h4>

```typescript theme={null}
open(): Promise<Snapshot>
```

Open and metadata-validate the underlying artifact. Throws if this handle is read-only (came from [`Snapshot.list()`](#snapshot-list)); fetch a live handle via [`Snapshot.get()`](#snapshot-get) first.

<h4 id="snapshothandleremove">
  <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">remove()</span>
</h4>

```typescript theme={null}
remove(opts?: { force?: boolean }): Promise<void>
```

Remove this installed snapshot copy and its index row using the handle's stored artifact path. Other groups containing the same snapshot ID or digest remain unchanged. Refuses if the snapshot has indexed children unless `force` is set. Throws if this handle is read-only.

<Accordion title="Example">
  ```typescript theme={null}
  const h = await Snapshot.get("baseline:deps");
  const snap = await h.open();          // metadata-validated
  await h.remove({ force: false });     // refuse if it has children
  ```
</Accordion>

| Field | Type | Description |
| - | - | - |
| <span id="snapshothandle-reference" />`reference` | `string` | Backend-relative snapshot reference. |
| <span id="snapshothandle-referencekind" />`referenceKind` | `"id" \| "path"` | How the backend resolves the reference. |

<h4 id="snapshothandlesaveto">
  <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">saveTo()</span>
</h4>

```typescript theme={null}
saveTo(out: string, opts?: SaveOpts): Promise<void>
```

Bundle the referenced snapshot through the backend retained by the handle.
Handles returned by `Snapshot.list()` are metadata-only; fetch a live handle
with `Snapshot.get()` first. Cloud returns `UnsupportedError`.

***

## SnapshotBuilder

Fluent builder for a snapshot, returned by [`Snapshot.builder(name)`](#snapshotbuilder). Every setter mutates in place and returns `this`, so calls chain. The source sandbox is required: call [`.fromSandbox()`](#fromsandbox) before [`.create()`](#create).

***

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

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

```typescript theme={null}
fromSandbox(sourceSandbox: string): this
```

Set the sandbox to capture. Required; [`.create()`](#create) fails without it.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>sourceSandbox</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Name of the source sandbox. Local disk capture supports running, paused, stopped, and crashed sources. Cloud requires a stopped persistent source.</div>
  </div>
</div>

***

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

```typescript theme={null}
group(name: string): this
```

Set the local snapshot group. Defaults to the source sandbox’s name. Direct archive capture does not accept a group.

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

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

```typescript theme={null}
destDir(destDir: string): this
```

Create the snapshot group under this parent directory instead of the default snapshots store. Member names are local aliases within the group; stable snapshot IDs identify immutable artifacts.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>destDir</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Parent directory to create the artifact in (e.g. a larger volume).</div>
  </div>
</div>

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

```typescript theme={null}
label(key: string, value: string): this
```

Add a `key=value` label to the snapshot manifest. May be called repeatedly.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>key</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Label key.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>value</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Label value.</div>
  </div>
</div>

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

```typescript theme={null}
force(): this
```

Overwrite an existing direct archive output file. Installed group members are immutable, so installed creation rejects this option.

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

```typescript theme={null}
recordIntegrity(): this
```

Compute and record a content-integrity hash of the upper layer at creation time, so the snapshot can be verified later or across a trust boundary.

***

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

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

```typescript theme={null}
full(): this
```

Local-only: capture disk, memory, and execution state. The source must be running or paused and returns to that state after capture.

***

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

```typescript theme={null}
guestFlush(policy: GuestFlush): this
```

Select guest writeback before capture. `GuestFlush` is `"auto" | "required" | "skip"`; defaults to `"auto"`. See [guest writeback](#guest-writeback).

***

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

```typescript theme={null}
create(): Promise<Snapshot>
```

<Accordion title="Example">
  ```typescript theme={null}
  const snap = await Snapshot.builder("baseline-v2")
    .fromSandbox("baseline")
    .recordIntegrity()
    .create();
  ```
</Accordion>

Capture the configured snapshot and return the resulting artifact.

<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">Promise\<Snapshot></a></div>
    <div className="msb-param-desc">The created snapshot artifact.</div>
  </div>
</div>

## SnapshotCopyBuilder

Returned by [`snapshot.copyTo()`](#snap-copyto). Each setter mutates the builder
and returns `this`.

| Method | Returns | Description |
| - | - | - |
| `labels(Record<string, string>)` | `this` | Replace all labels in the copied manifest |
| `recordIntegrity(boolean)` | `this` | Compute integrity when true, or omit it when false |
| `save()` | `Promise<void>` | Write the configured archive |

## RestoreBuilder

Restore into a new detached sandbox. Disk boots fresh; full resumes execution. See [restore examples](/sandboxes/snapshots#disk-snapshots) and [progress](/sandboxes/snapshots#restore-progress).

<Accordion title="Example">
  ```typescript theme={null}
  const child = await Sandbox.restore("api:baseline")
    .name("api-restored")
    .cowMemory()
    .restore();
  ```
</Accordion>

| Control | Purpose |
| - | - |
| `cowMemory()` | Share unchanged full-snapshot memory. |
| `.forked()` | Deprecated alias for the same CoW memory policy; see [migration notes](/sandboxes/snapshots#migrating-restore-options). |
| `diskOnly()` | Boot only the saved disk. |
| `snapshotBase(base)` | Supply an archive dependency. |
| `restore()` | Return the restored sandbox. |
| `restoreWithProgress()` | Return progress events; await `awaitSandbox()` for the sandbox. |

Image, replacement, and startup-command options are not accepted. Full restore requires matching CPU and memory settings, keeps captured network devices, and cannot apply a new guest security profile. Use disk-only restore to change these.

Full restore rejects missing external filesystems and additional disks by default. Use `allowMissingResources()` to resume with unavailable devices and warnings. This is separate from strict/relaxed validation of supplied mappings; inheritance does not waive missing backing. Root and owned storage remain required.

<Accordion title="Destination options">
  | Option | Purpose |
  | - | - |
  | `cpus(), memory()` | CPU count and memory in MiB. Full restore must match capture. |
  | `networkPolicy()` | Replace host traffic filtering; guest DNS and TLS settings stay unchanged. |
  | `maxConnections()` | Concurrent TCP limit; zero means unlimited. |
  | `disableNetwork()` | Remove the NIC. Rejected for full snapshots that captured one. |
  | `security()` | Guest security profile. Disk boot only, including an explicit default profile. |
  | `maxDuration(), idleTimeout()` | Lifetime and idle limits. Omitted means unlimited; zero expires immediately. |
  | `volume()` | Map host volumes or select captured private volumes. |
  | `port(), portBind(), portUdp(), portUdpBind()` | Bind destination TCP or UDP ports. |
  | `vsock(), vsockDgram()` | Bind destination vsock endpoints. |
  | `user(), logLevel()` | Default user for new execs and host runtime log level. |
  | `dangerouslyInheritResources()` | Explicitly inherit host resources. Disabled by default. |
  | `allowMissingResources()` | Allow unavailable external filesystems or additional disks, with warnings. Full restore otherwise requires their bindings. |
  | `externalMountPolicy()` | Validate supplied filesystem mappings: strict (default) or relaxed. Does not grant access. |

  Omitted controls retain destination defaults. Durations are non-negative finite seconds, rounded up. Network policy accepts `NetworkPolicy` or `NetworkPolicyBuilder`. Use `v => v.captured()` for a private captured volume.
</Accordion>

<span id="disk-maintenance-and-incremental-export" />

## Compaction

Compact a local sandbox’s root or owned disks. See [compaction](/sandboxes/snapshots#compact-disks) for examples and recovery requirements.

<Accordion title="Options and results">
  | Option | Purpose |
  | - | - |
  | `disk` | Select one owned disk by guest path; `/` selects the root. |
  | `rootDiskOnly` | Select only the root. Cannot combine with the disk selector. |
  | `layers` | Oldest sealed layers to merge, including the base. Minimum two; omit for all. Excludes the writable layer. |
  | `dryRun` | Preview without changing storage. |

  Defaults to the root and owned data disks; excludes named/external volumes and directories. Requires a running or fully stopped local sandbox. Fewer than two sealed layers means no change; no eligible disks returns an empty result with zero counts.

  Results include aggregate counts and per-disk entries keyed by `guestPath`. `materializedBytes` counts copied bytes, not reclaimed space. Times are microseconds: per-disk `totalUs` covers preparation; aggregate `totalUs` also includes switching; `pauseUs` measures the shared VM pause.
</Accordion>

## Types

### SaveOpts <span className="msb-tag is-type">interface</span>

Bundle options for [`Snapshot.save()`](#snapshot-save) and instance `saveTo()` methods. Boolean fields default to `false`; selective-export fields are omitted by default.

<p className="msb-backref">Used by <a href="#snapshot-save">Snapshot.save()</a> and instance <code>saveTo()</code> methods</p>

| Field | Type | Description |
| - | - | - |
| `since` | `string` | Omit disk layers and RAM objects supplied by an exact base; incompatible with `lastLayers` and `withParents`. |
| `lastLayers` | `number` | Include the newest N sealed root-disk layers; owned disks and full execution state remain complete. |
| `withParents` | `boolean` | Walk the parent chain and include each ancestor in the archive. |
| `withImage` | `boolean` | Include the OCI image cache so the archive boots offline. |
| `plainTar` | `boolean` | Skip zstd compression and write a plain `.tar`. |

***

### SnapshotScope <span className="msb-tag is-type">type</span>

Scope of what a snapshot captures: `"disk"` for filesystem state or `"full"` for disk plus VM execution state.

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

```typescript theme={null}
type SnapshotScope = "disk" | "full";
```

***

### SnapshotVerifyReport <span className="msb-tag is-type">union</span>

Result of [`snap.verify()`](#snap-verify). Checkpoint snapshots add `checkpoint: { kind: "verified", root: string }`; the existing `upper` projection stays intact for disk-snapshot compatibility.

<p className="msb-backref">Returned by <a href="#snap-verify">snap.verify()</a></p>

```typescript theme={null}
type SnapshotVerifyReport =
  | {
      readonly digest: string;
      readonly path: string;
      readonly upper: { readonly kind: "notRecorded" };
      readonly checkpoint?: { readonly kind: "verified"; readonly root: string };
    }
  | {
      readonly digest: string;
      readonly path: string;
      readonly upper: {
        readonly kind: "verified";
        readonly algorithm: string;
        readonly digest: string;
      };
      readonly checkpoint?: { readonly kind: "verified"; readonly root: string };
    };
```

| Field | Type | Description |
| - | - | - |
| `digest` | `string` | Snapshot's manifest digest. |
| `path` | `string` | Artifact directory path. |
| `upper.kind` | `"notRecorded" \| "verified"` | Whether an integrity hash was recorded and checked. |
| `upper.algorithm` | `string` | Hash algorithm (`"verified"` only). |
| `checkpoint` | `{ kind: "verified"; root: string }` | Verified checkpoint closure identity when state is full. |
| `upper.digest` | `string` | Recomputed upper-layer digest (`"verified"` only). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.