Snapshots

TypeScript 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 portable artifacts; cloud snapshots use managed storage or the organization’s host volume.

import { Sandbox, Snapshot, SnapshotHandle } from "microsandbox";
import type { SaveOpts, SnapshotScope, SnapshotVerifyReport } from "microsandbox";

Snapshots are disk-only and require a sandbox that is not running (stopped or crashed). listDir, reindex, save/saveTo, load, and verify keep the same API on every backend, but currently reject with UnsupportedError in cloud.

Capture and boot

These entry points live on SandboxBuilder and SandboxHandle; they are the bridge between sandboxes and snapshot artifacts.

.fromSnapshot()

fromSnapshot(snapshot: string | Snapshot | SnapshotHandle): SandboxBuilder

Example

const sb = await Sandbox.builder("worker")
  .fromSnapshot("after-pip-install")
  .create();

Boot a fresh sandbox from a snapshot. Mutually exclusive with .image(); the snapshot already pins the image. Passing a Snapshot or SnapshotHandle preserves its backend-relative reference automatically.

Parameters

snapshotstring | Snapshot | SnapshotHandle

Backend-relative string or snapshot object returned by this SDK.

Returns

SandboxBuilder

The same builder, for chaining.

handle.snapshot()

snapshot(name: string): Promise<Snapshot>

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

Parameters

namestring

Snapshot name. Local stores it in the default snapshot directory; cloud creates a managed snapshot.

Returns

Promise<Snapshot>

The created snapshot artifact.

Example

const h = await Sandbox.get("baseline");
await h.stop();
const snap = await h.snapshot("after-pip-install");

---

Snapshot static methods

Snapshot.builder()

static builder(name: string): SnapshotBuilder

Begin building a new snapshot named name through the active backend. With no destination, local uses its default snapshot directory and cloud uses managed storage. .destDir() selects a local parent or cloud host-volume directory.

Parameters

namestring

Snapshot name. Its storage location is selected by the active backend.

Returns

SnapshotBuilder

Builder for configuring the snapshot.

Example

const snap = await Snapshot.builder("after-pip-install")
  .fromSandbox("baseline")
  .label("stage", "post-deps")
  .recordIntegrity()
  .create();

---

Snapshot.open()

static open(pathOrName: string): Promise<Snapshot>

Example

const snap = await Snapshot.open("after-pip-install");
console.log(snap.digest);

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() for content checks where supported.

Parameters

pathOrNamestring

Backend-relative snapshot name, ID, or path.

Returns

Promise<Snapshot>

The opened snapshot.

Snapshot.get()

static get(nameOrDigest: string): Promise<SnapshotHandle>

Example

const h = await Snapshot.get("after-pip-install");
console.log(h.digest, h.createdAt);

Look up a snapshot through the active backend and return a lightweight SnapshotHandle.

Parameters

nameOrDigeststring

Public identifier understood by the active backend, such as a local name/digest or cloud snapshot ID.

Returns

Promise<SnapshotHandle>

Lightweight handle returned by the active backend.

Snapshot.list()

static list(): Promise<SnapshotHandle[]>

Example

for (const h of await Snapshot.list()) {
  console.log(h.name ?? h.digest, h.sizeBytes);
}

List snapshots visible through the active backend. Cloud lists managed snapshots; host-volume artifacts are opened explicitly by reference.

Returns

Promise<SnapshotHandle[]>

All indexed snapshot handles.

Snapshot.listDir()

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.

Parameters

dirstring

Directory to scan for artifact subdirectories.

Returns

Promise<Snapshot[]>

Parsed snapshots found in the directory.

Snapshot.remove()

static remove(pathOrName: string, opts?: { force?: boolean }): Promise<void>

Example

await Snapshot.remove("after-pip-install", { force: true });

Remove a snapshot through the active backend. Locally, the string may be a path, name, or digest and removal refuses indexed children unless force is set. In cloud, the string identifies a managed or host-volume snapshot.

Parameters

pathOrNamestring

Path, name, or digest of the snapshot to remove.

opts.forceboolean

Remove even if the snapshot has indexed children. Defaults to false.

Snapshot.reindex()

static reindex(dir?: string): Promise<number>

Example

const count = await Snapshot.reindex();
console.log(`reindexed ${count} snapshots`);

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

Parameters

dirstring

Directory to scan. Defaults to the configured snapshots dir.

Returns

Promise<number>

Count of artifacts indexed.

---

Snapshot.save()

staticasync

static save(nameOrPath: string, out: string, opts?: SaveOpts): Promise<void>

Bundle a local snapshot into a .tar.zst archive. The recorded manifest is archived as-is, so create the snapshot with recordIntegrity() if receivers must verify content. See SaveOpts for bundling options. Cloud returns UnsupportedError.

Parameters

nameOrPathstring

Name or path of the snapshot to bundle.

outstring

Output archive path.

optsSaveOpts

Bundling options. All fields default to false.

Example

await Snapshot.save("after-pip-install", "./baseline.tar.zst", {
  withImage: true,
});

---

Snapshot.load()

staticasync

static load(archive: string, dest?: string): Promise<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(). Compression is detected from magic bytes. Cloud returns UnsupportedError.

Parameters

archivestring

Path to the archive to unpack.

deststring

Destination directory. Defaults to the snapshots directory.

Returns

Promise<SnapshotHandle>

Handle to the loaded snapshot.

Example

const h = await Snapshot.load("./baseline.tar.zst");
console.log("loaded", h.digest);

---

Snapshot instance members

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

snap.reference

get reference(): string

Stable value accepted by SandboxBuilder.fromSnapshot().

snap.referenceKind

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

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

snap.digest

get digest(): string

Canonical content digest (sha256:hex). The snapshot’s identity.

snap.sizeBytes

get sizeBytes(): bigint

Backend-reported stored payload size in bytes.

snap.imageRef

get imageRef(): string

Image reference the snapshot was taken from.

snap.imageManifestDigest

get imageManifestDigest(): string

OCI manifest digest of the pinned image.

snap.format

get format(): "raw" | "qcow2"

On-disk format of the upper layer.

---

snap.scope

getter

get scope(): SnapshotScope

Snapshot scope: "disk" for a disk-only snapshot, "resumable" once resumable snapshots land. Always "disk" today. See SnapshotScope.

---

snap.fstype

get fstype(): string

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

snap.parent

get parent(): string | null

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

snap.createdAt

get createdAt(): string

RFC 3339 timestamp when the snapshot was created.

snap.labels

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

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

snap.sourceSandbox

get sourceSandbox(): string | null

Best-effort source-sandbox name, if recorded. null when the manifest has no source recorded.

snap.saveTo()

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.

await snap.saveTo("./baseline.tar.zst", { withImage: true });

snap.verify()

verify(): Promise<SnapshotVerifyReport>

Example

const report = await snap.verify();
if (report.upper.kind === "verified") {
  console.log(`hash matches: ${report.upper.digest}`);
} else {
  console.log("no integrity hash recorded");
}

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. The report’s upper.kind is "notRecorded" when no integrity was recorded. The cloud backend currently rejects this operation with UnsupportedError.

Returns

Promise<SnapshotVerifyReport>

Verification result.

SnapshotBuilder

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

---

.fromSandbox()

builder

fromSandbox(sourceSandbox: string): this

Set the sandbox to capture. Required; .create() fails without it.

Parameters

sourceSandboxstring

Name of the stopped sandbox to capture.

---

.destDir()

builder

destDir(destDir: string): this

Create the artifact under this parent directory instead of the default snapshots store. The artifact directory is destDir/<name>; the name stays the snapshot’s identity either way.

Parameters

destDirstring

Parent directory to create the artifact in (e.g. a larger volume).

.label()

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

force(): this

Overwrite an existing artifact with the same name instead of failing on conflict.

.recordIntegrity()

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.

---

.resumable()

builder

resumable(): this

Request a "resumable" snapshot (disk plus VM state). Accepted by the builder, but .create() currently returns an Unsupported error; resumable snapshots have not landed yet.

---

.create()

create(): Promise<Snapshot>

Example

const snap = await Snapshot.builder("baseline-v2")
  .fromSandbox("baseline")
  .force()
  .recordIntegrity()
  .create();

Capture the configured snapshot and return the resulting artifact.

Returns

Promise<Snapshot>

The created snapshot artifact.

Types

SnapshotHandle class

Lightweight handle returned by the active backend. Values are snapshotted at construction time; call Snapshot.get() again for a fresh reading if needed. Handles from Snapshot.list() are read-only; fetch a live handle via Snapshot.get() for lifecycle methods.

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

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.
scope	SnapshotScope	Snapshot payload scope ("disk" today).
imageRef	string	Image reference the snapshot was taken from.
format	"raw" | "qcow2"	On-disk format of the upper layer.
sizeBytes	bigint | null	Backend-reported stored payload size, when known.
createdAt	Date	Snapshot creation time (from manifest).
reference	string	Stable backend-relative restore reference.
referenceKind	"id" | "path"	How the selected backend resolves the reference.
open()	Promise<Snapshot>	Open and metadata-validate the underlying artifact.
remove(opts?)	Promise<void>	Remove the artifact and its index row; refuses on children unless force.
saveTo(out, opts?)	Promise<void>	Bundle through the backend retained by this handle.

snapshotHandle.open()

open(): Promise<Snapshot>

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

snapshotHandle.remove()

remove(opts?: { force?: boolean }): Promise<void>

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.

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

snapshotHandle.saveTo()

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.

---

SaveOpts interface

Bundle options for Snapshot.save() and instance saveTo() methods. All fields default to false.

Used by Snapshot.save() and instance saveTo() methods

Field	Type	Description
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 type

Scope of what a snapshot captures. Every snapshot today is "disk"; "resumable" (disk plus VM state) is reserved for resumable snapshots.

Returned by snap.scope · SnapshotHandle.scope

type SnapshotScope = "disk" | "resumable";

---

SnapshotVerifyReport union

Result of 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()

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