--- title: Snapshots description: TypeScript SDK - Snapshot API reference --- Capture the disk state of a stopped sandbox into a portable artifact, then boot fresh sandboxes from it. See [Snapshots](/sandboxes/snapshots) for concepts and walkthroughs. ```typescript import { Sandbox, Snapshot, SnapshotHandle } from "microsandbox"; import type { ExportOpts, SnapshotVerifyReport } from "microsandbox"; ``` Snapshots are **disk-only** and require a sandbox that is not running (stopped or crashed).

Capture & boot3

.fromSnapshot()boot a sandbox from a snapshot handle.snapshot()snapshot a stopped sandbox by name handle.snapshotTo()snapshot to an explicit path

Snapshot · static9

Snapshot.builder()configure a new snapshot Snapshot.open()open an existing artifact Snapshot.get()indexed handle by name or digest Snapshot.list()indexed snapshots Snapshot.listDir()parse a directory, no index Snapshot.remove()delete an artifact Snapshot.reindex()rebuild the local index Snapshot.export()bundle into an archive Snapshot.import()unpack an archive

Snapshot · instance12

snap.pathartifact directory snap.digestcanonical content digest snap.sizeBytesapparent upper-layer size snap.imageRefsource image reference snap.imageManifestDigestpinned image manifest digest snap.formatupper-layer on-disk format snap.fstypeupper-layer filesystem type snap.parentparent digest, or null snap.createdAtcreation timestamp snap.labelsuser labels snap.sourceSandboxrecorded source sandbox snap.verify()recheck content hash

Builder · SnapshotBuilder6

.name() .path() .label() .force() .recordIntegrity() .create()

SnapshotHandle2

snapshotHandle.open()open the underlying artifact snapshotHandle.remove()delete artifact and index row

Types

SnapshotHandle ExportOpts SnapshotVerifyReport

Typical flow

```typescript import { Sandbox, Snapshot } from "microsandbox"; // 1. capture: stop the sandbox, then snapshot its disk const sb = await Sandbox.get("baseline"); await sb.stop(); const snap = await Snapshot.builder("baseline") .name("after-pip-install") // bare name in the default dir .recordIntegrity() // hash the upper layer .create(); // 2. boot a fresh sandbox from the snapshot const fresh = await Sandbox.builder("worker") .fromSnapshot(snap.path) .create(); ``` ## Capture and boot These entry points live on `SandboxBuilder` and `SandboxHandle`; they are the bridge between sandboxes and snapshot artifacts. --- #### .fromSnapshot()
builder
```typescript fromSnapshot(pathOrName: string): SandboxBuilder ``` Boot a fresh sandbox from a snapshot artifact. Mutually exclusive with [`.image()`](/sdk/typescript/sandbox#image) — the snapshot already pins the image. Documented in full on the [Sandbox](/sdk/typescript/sandbox#fromsnapshot) page.

Parameters

pathOrNamestring
Bare name (resolved under the default snapshots directory) or filesystem path to an artifact directory.

Returns

SandboxBuilder
The same builder, for chaining.
```typescript const sb = await Sandbox.builder("worker") .fromSnapshot("after-pip-install") .create(); ``` --- #### handle.snapshot()
instanceasync
```typescript snapshot(name: string): Promise ``` Snapshot this sandbox under a bare name in the default snapshots directory (`~/.microsandbox/snapshots//`). Called on a [`SandboxHandle`](/sdk/typescript/sandbox#sandboxhandle). The sandbox must be stopped or crashed; running sandboxes are rejected with a `SnapshotSandboxRunning` error. For an explicit filesystem destination, see [`snapshotTo()`](#handle-snapshotto).

Parameters

namestring
Bare name; becomes the artifact directory under the default snapshots dir.

Returns

Promise<Snapshot>
The created snapshot artifact.
```typescript const h = await Sandbox.get("baseline"); await h.stop(); const snap = await h.snapshot("after-pip-install"); ``` --- #### handle.snapshotTo()
instanceasync
```typescript snapshotTo(path: string): Promise ``` Snapshot this sandbox to an explicit filesystem path. Called on a [`SandboxHandle`](/sdk/typescript/sandbox#sandboxhandle). The sandbox must be stopped or crashed.

Parameters

pathstring
Destination artifact directory path.

Returns

The created snapshot artifact.
```typescript const snap = await h.snapshotTo("/data/snapshots/baseline-v2"); ``` --- ## Snapshot static methods --- #### Snapshot.builder()
static
```typescript static builder(sourceSandbox: string): SnapshotBuilder ``` Begin building a new snapshot of `sourceSandbox` (which must be stopped). The fluent builder is what powers the CLI internally. The bare-name and explicit-path destinations are mutually exclusive — call exactly one of [`.name()`](#name) or [`.path()`](#path). See [`SnapshotBuilder`](#snapshotbuilder) for all setters.

Parameters

sourceSandboxstring
Name of the stopped sandbox to capture.

Returns

Builder for configuring the snapshot.
```typescript const snap = await Snapshot.builder("baseline") .name("after-pip-install") .label("stage", "post-deps") .recordIntegrity() .create(); ``` --- #### Snapshot.open()
staticasync
```typescript static open(pathOrName: string): Promise ``` Open an existing snapshot artifact. Bare names resolve under the default snapshots directory; anything else is treated as a path. Cheap metadata validation only — does not read the upper file. Use [`verify()`](#snap-verify) for content checks.

Parameters

pathOrNamestring
Bare name (resolved under the default snapshots dir) or filesystem path.

Returns

The opened snapshot.
```typescript const snap = await Snapshot.open("after-pip-install"); console.log(snap.digest); ``` --- #### Snapshot.get()
staticasync
```typescript static get(nameOrDigest: string): Promise ``` Look up an indexed snapshot by digest, name, or path. Returns a lightweight [`SnapshotHandle`](#snapshothandle-class) backed by the local index row.

Parameters

nameOrDigeststring
Name, digest (sha256:...), or path of an indexed snapshot.

Returns

Index-backed handle.
```typescript const h = await Snapshot.get("after-pip-install"); console.log(h.digest, h.createdAt); ``` --- #### Snapshot.list()
staticasync
```typescript static list(): Promise ``` List indexed snapshots from the local DB cache.

Returns

All indexed snapshot handles.
```typescript for (const h of await Snapshot.list()) { console.log(h.name ?? h.digest, h.sizeBytes); } ``` --- #### Snapshot.listDir()
staticasync
```typescript static listDir(dir: string): Promise ``` Walk a directory and parse each subdirectory's manifest. Does not touch the index — useful for inspecting external snapshot collections that were never imported. Skips entries that don't look like snapshot artifacts.

Parameters

dirstring
Directory to scan for artifact subdirectories.

Returns

Parsed snapshots found in the directory.
```typescript const found = await Snapshot.listDir("/mnt/external/snapshots"); console.log(`${found.length} artifacts`); ``` --- #### Snapshot.remove()
staticasync
```typescript static remove(pathOrName: string, opts?: { force?: boolean }): Promise ``` Remove a snapshot by path, name, or digest. Refuses if the snapshot has indexed children unless `force` is set.

Parameters

pathOrNamestring
Path, name, or digest of the snapshot to remove.
opts.forceboolean
Remove even if the snapshot has indexed children. Defaults to false.
```typescript await Snapshot.remove("after-pip-install", { force: true }); ``` --- #### Snapshot.reindex()
staticasync
```typescript static reindex(dir?: string): Promise ``` Walk the snapshots directory (default: the configured snapshots dir) and rebuild the local index. Returns the number of artifacts indexed.

Parameters

dirstring
Directory to scan. Defaults to the configured snapshots dir.

Returns

Promise<number>
Count of artifacts indexed.
```typescript const count = await Snapshot.reindex(); console.log(`reindexed ${count} snapshots`); ``` --- #### Snapshot.export()
staticasync
```typescript static export(nameOrPath: string, out: string, opts?: ExportOpts): Promise ``` Bundle a snapshot into a `.tar.zst` archive. When the snapshot has no integrity hash yet, one is computed and embedded in the bundled manifest so the receiver can verify. See [`ExportOpts`](#exportopts-interface) for bundling options.

Parameters

nameOrPathstring
Name or path of the snapshot to bundle.
outstring
Output archive path.
Bundling options. All fields default to false.
```typescript await Snapshot.export("after-pip-install", "./baseline.tar.zst", { withImage: true, }); ``` --- #### Snapshot.import()
staticasync
```typescript static import(archive: string, dest?: string): Promise ``` Unpack a snapshot archive (`.tar.zst` or `.tar`) into the snapshots directory, verifying recorded integrity on the way in. Compression is detected from magic bytes.

Parameters

archivestring
Path to the archive to unpack.
deststring
Destination directory. Defaults to the snapshots directory.

Returns

Handle to the imported snapshot.
```typescript const h = await Snapshot.import("./baseline.tar.zst"); console.log("imported", h.digest); ``` --- ## Snapshot instance members {#snapshot-instance} A `Snapshot` is a snapshot artifact on disk. The artifact is a directory containing `manifest.json` and the captured `upper.ext4`. The directory is the source of truth; the local DB index is just a rebuildable cache. Returned by [`Snapshot.builder().create()`](#snapshotbuilder), [`Snapshot.open()`](#snapshot-open), [`handle.snapshot()`](#handle-snapshot), and [`handle.snapshotTo()`](#handle-snapshotto). --- #### snap.path
getter
```typescript get path(): string ``` Path to the artifact directory. --- #### snap.digest
getter
```typescript get digest(): string ``` Canonical content digest (`sha256:hex`). The snapshot's identity. --- #### snap.sizeBytes
getter
```typescript get sizeBytes(): bigint ``` Apparent size of the captured upper layer in bytes (sparse on disk). --- #### snap.imageRef
getter
```typescript get imageRef(): string ``` Image reference the snapshot was taken from. --- #### snap.imageManifestDigest
getter
```typescript get imageManifestDigest(): string ``` OCI manifest digest of the pinned image. --- #### snap.format
getter
```typescript get format(): "raw" | "qcow2" ``` On-disk format of the upper layer. --- #### snap.fstype
getter
```typescript get fstype(): string ``` Filesystem type inside the upper (e.g. `"ext4"`). --- #### snap.parent
getter
```typescript get parent(): string | null ``` Manifest digest of the parent snapshot, or `null` for a root. --- #### snap.createdAt
getter
```typescript get createdAt(): string ``` RFC 3339 timestamp when the snapshot was created. --- #### snap.labels
getter
```typescript get labels(): ReadonlyArray ``` User-supplied labels (sorted by key in canonical form), as `[key, value]` pairs. --- #### snap.sourceSandbox
getter
```typescript get sourceSandbox(): string | null ``` Best-effort source-sandbox name, if recorded. `null` when the manifest has no source recorded. --- #### snap.verify()
instanceasync
```typescript verify(): Promise ``` Recompute the upper layer's content hash and compare against the manifest. Walks data extents only, so a 4 GiB sparse file with a few MB of data verifies in milliseconds. The report's `upper.kind` is `"notRecorded"` when the manifest has no integrity hash recorded.

Returns

Verification result.
```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"); } ``` --- ## SnapshotBuilder Fluent builder for a snapshot, returned by [`Snapshot.builder(name)`](#snapshotbuilder). Every setter mutates in place and returns `this`, so calls chain. Pick exactly one destination: [`.name()`](#name) or [`.path()`](#path). --- #### .name()
builder
```typescript name(name: string): this ``` Set a bare name; the artifact lands under the default snapshots directory. Mutually exclusive with [`.path()`](#path).

Parameters

namestring
Bare snapshot name.
--- #### .path()
builder
```typescript path(path: string): this ``` Set an explicit filesystem path for the artifact. Mutually exclusive with [`.name()`](#name).

Parameters

pathstring
Destination artifact directory path.
--- #### .label()
builder
```typescript label(key: string, value: string): this ``` Add a `key=value` label to the snapshot manifest. May be called repeatedly.

Parameters

keystring
Label key.
valuestring
Label value.
--- #### .force()
builder
```typescript force(): this ``` Overwrite an existing artifact at the destination instead of failing on conflict. --- #### .recordIntegrity()
builder
```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. --- #### .create()
builderasync
```typescript create(): Promise ``` Capture the configured snapshot and return the resulting artifact.

Returns

The created snapshot artifact.
```typescript const snap = await Snapshot.builder("baseline") .path("/data/snapshots/baseline-v2") .force() .recordIntegrity() .create(); ``` --- ## Types --- ### SnapshotHandle class Lightweight handle backed by an index row. Values are snapshotted from the index at construction time — call [`Snapshot.get()`](#snapshot-get) again for a fresh reading if needed. Handles from [`Snapshot.list()`](#snapshot-list) are read-only and throw on [`open()`](#snapshothandleopen) / [`remove()`](#snapshothandleremove); fetch a live handle via [`Snapshot.get()`](#snapshot-get) for those lifecycle methods.

Returned by Snapshot.get(), Snapshot.list(), Snapshot.import()

| Member | Type | Description | |--------|------|-------------| | `digest` | `string` | Manifest digest (`sha256:hex`), the canonical identity. | | `name` | `string \| null` | Convenience name; `null` for digest-only entries. | | `parentDigest` | `string \| null` | Parent snapshot's manifest digest, or `null` for a root. | | `imageRef` | `string` | Image reference the snapshot was taken from. | | `format` | `"raw" \| "qcow2"` | On-disk format of the upper layer. | | `sizeBytes` | `bigint \| null` | Apparent size of the upper file at index time. | | `createdAt` | `Date` | Snapshot creation time (from manifest). | | `path` | `string` | Local artifact directory path. | | `open()` | `Promise<`[`Snapshot`](#snapshot-instance)`>` | Open and metadata-validate the underlying artifact. | | `remove(opts?)` | `Promise` | Remove the artifact and its index row; refuses on children unless `force`. |

snapshotHandle.open()

```typescript open(): Promise ``` 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.

snapshotHandle.remove()

```typescript remove(opts?: { force?: boolean }): Promise ``` Remove the artifact and its index row. Refuses if the snapshot has indexed children unless `force` is set. Throws if this handle is read-only. ```typescript const h = await Snapshot.get("after-pip-install"); const snap = await h.open(); // metadata-validated await h.remove({ force: false }); // refuse if it has children ``` --- ### ExportOpts interface Bundle options for [`Snapshot.export()`](#snapshot-export). All fields default to `false`.

Used by Snapshot.export()

| Field | Type | Description | |-------|------|-------------| | `withParents` | `boolean` | Walk the parent chain and include each ancestor (no-op in v1). | | `withImage` | `boolean` | Include the OCI image cache so the archive boots offline. | | `plainTar` | `boolean` | Skip zstd compression and write a plain `.tar`. | --- ### SnapshotVerifyReport union Result of [`snap.verify()`](#snap-verify). The `upper` discriminant is `"notRecorded"` when no integrity hash was stored at create time, or `"verified"` when the recorded hash matched the recomputed one.

Returned by snap.verify()

```typescript type SnapshotVerifyReport = | { readonly digest: string; readonly path: string; readonly upper: { readonly kind: "notRecorded" }; } | { readonly digest: string; readonly path: string; readonly upper: { readonly kind: "verified"; readonly algorithm: string; readonly digest: 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). | | `upper.digest` | `string` | Recomputed upper-layer digest (`"verified"` only). |