---
title: Snapshots
description: TypeScript SDK - Snapshot API reference
keywords: ["TypeScript SDK", "TypeScript snapshots", "microsandbox snapshots"]
---

<Tooltip tip="Cloud supports disk capture from stopped or crashed 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>

Create and manage snapshots. 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
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
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
createArchive(out: string, plainTar?: boolean): Promise<SnapshotArchive>
```

Capture directly into an archive without installing a local snapshot.

<Accordion title="Example">

```typescript
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
static open(pathOrName: string): Promise<Snapshot>
```

<Accordion title="Example">

```typescript
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&lt;Snapshot&gt;</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
static get(nameOrDigest: string): Promise<SnapshotHandle>
```

<Accordion title="Example">

```typescript
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&lt;SnapshotHandle&gt;</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
static list(): Promise<SnapshotHandle[]>
```

<Accordion title="Example">

```typescript
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&lt;SnapshotHandle[]&gt;</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
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&lt;Snapshot[]&gt;</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
static remove(pathOrName: string, opts?: { force?: boolean }): Promise<void>
```

<Accordion title="Example">

```typescript
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
static reindex(dir?: string): Promise<number>
```

<Accordion title="Example">

```typescript
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&lt;number&gt;</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
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
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
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&lt;SnapshotHandle&gt;</a></div>
    <div className="msb-param-desc">Handle to the loaded snapshot.</div>
  </div>
</div>

<Accordion title="Example">

```typescript
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
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
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
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
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). Live disk captures preserve the source's running or paused state. 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&lt;Snapshot&gt;</a></div>
    <div className="msb-param-desc">The created snapshot artifact.</div>
  </div>
</div>

<Accordion title="Example">

```typescript
const h = await Sandbox.get("baseline");
await h.stop();
const snap = await h.snapshot("deps");
```

</Accordion>

---

## Snapshot instance members {#snapshot-instance}

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

#### <span className="msb-recv">snap.</span><span className="msb-hn">id</span>

```typescript
get id(): string
```

Stable opaque `snap_...` identity, separate from the descriptor digest.

#### <span className="msb-recv">snap.</span><span className="msb-hn">path</span>

```typescript
get path(): string
```

Local artifact directory. Throws `UnsupportedError` for cloud snapshots; use the snapshot object or its typed reference for backend-neutral operations.

#### <span className="msb-recv">snap.</span><span className="msb-hn">reference</span>

```typescript
get reference(): string
```

Stable backend-relative value. Pass the snapshot object to `Sandbox.restore(snapshot)` to preserve both this value and its reference kind.

#### <span className="msb-recv">snap.</span><span className="msb-hn">referenceKind</span>

```typescript
get referenceKind(): "id" | "path"
```

How the selected backend resolves `reference`. Most callers can pass the
snapshot object directly and never inspect this value.

#### <span className="msb-recv">snap.</span><span className="msb-hn">digest</span>

```typescript
get digest(): string
```

Canonical descriptor digest (`sha256:hex`), separate from the stable snapshot ID.

#### <span className="msb-recv">snap.</span><span className="msb-hn">sizeBytes</span>

```typescript
get sizeBytes(): bigint | null
```

Backend-reported stored payload size in bytes, or `null` when unavailable.

#### <span className="msb-recv">snap.</span><span className="msb-hn">imageRef</span>

```typescript
get imageRef(): string
```

Image reference the snapshot was taken from.

#### <span className="msb-recv">snap.</span><span className="msb-hn">imageManifestDigest</span>

```typescript
get imageManifestDigest(): string
```

OCI manifest digest of the pinned image.

#### <span className="msb-recv">snap.</span><span className="msb-hn">format</span>

```typescript
get format(): "raw" | "qcow2" | null
```

On-disk format of the upper layer.

---

#### <span className="msb-recv">snap.</span><span className="msb-hn">scope</span>
<div className="msb-tags"><span className="msb-tag is-instance">getter</span></div>

```typescript
get scope(): SnapshotScope
```

Snapshot scope: `"disk"` for a disk-only snapshot or `"full"` for disk plus VM execution state. See [`SnapshotScope`](#snapshotscope-type).

---

#### <span className="msb-recv">snap.</span><span className="msb-hn">fstype</span>

```typescript
get fstype(): string | null
```

Filesystem type inside the upper (e.g. `"ext4"`).

#### <span className="msb-recv">snap.</span><span className="msb-hn">parent</span>

```typescript
get parent(): string | null
```

Manifest digest of the parent snapshot, or `null` for a root.

#### <span className="msb-recv">snap.</span><span className="msb-hn">createdAt</span>

```typescript
get createdAt(): string
```

RFC 3339 timestamp when the snapshot was created.

#### <span className="msb-recv">snap.</span><span className="msb-hn">labels</span>

```typescript
get labels(): ReadonlyArray<readonly [string, string]>
```

User-supplied labels (sorted by key in canonical form), as `[key, value]` pairs.

#### <span className="msb-recv">snap.</span><span className="msb-hn">sourceSandbox</span>

```typescript
get 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
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
await snap.saveTo("./baseline.tar.zst", { withImage: true });
```

</Accordion>

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

```typescript
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
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
verify(): Promise<SnapshotVerifyReport>
```

<Accordion title="Example">

```typescript
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&lt;SnapshotVerifyReport&gt;</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>

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">digest</span>

`string`

Descriptor digest (`sha256:hex`), separate from the stable snapshot ID.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">name</span>

`string \| null`

Member name within its group, or `null` when no alias is recorded.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">parentDigest</span>

`string \| null`

Parent snapshot's manifest digest, or `null` for a root.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">scope</span>

[`SnapshotScope`](#snapshotscope-type)

Snapshot payload scope (`"disk"` today).

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">imageRef</span>

`string`

Image reference the snapshot was taken from.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">format</span>

`"raw" \| "qcow2"`

On-disk format of the upper layer.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">sizeBytes</span>

`bigint \| null`

Apparent size of the upper file at index time.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">createdAt</span>

`Date`

Snapshot creation time (from manifest).

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">path</span>

`string`

Local artifact directory path.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">open()</span> {#snapshothandleopen}

```typescript
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.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">remove()</span> {#snapshothandleremove}

```typescript
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
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>
#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">reference</span>

```typescript
get reference(): string
```

Backend-relative snapshot reference.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">referenceKind</span>

```typescript
get referenceKind(): "id" | "path"
```

How the backend resolves the reference.

#### <span className="msb-recv">snapshotHandle.</span><span className="msb-hn">saveTo()</span> {#snapshothandlesaveto}

```typescript
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
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. Disk capture supports running, paused, stopped, and crashed sources.</div>
  </div>
</div>

---

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

```typescript
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
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
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
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
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
full(): this
```

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
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
create(): Promise<Snapshot>
```

<Accordion title="Example">

```typescript
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&lt;Snapshot&gt;</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
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
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
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). |