Snapshots - microsandbox

Capture the disk state of a stopped sandbox into a portable artifact, then boot fresh sandboxes from it. See Snapshots for concepts and walkthroughs.

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

Typical flow

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("after-pip-install")
  .fromSandbox("baseline")       // sandbox to capture
  .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()

fromSnapshot(pathOrName: string): SandboxBuilder

Example

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

Boot a fresh sandbox from a snapshot artifact. Mutually exclusive with .image(); the snapshot already pins the image. Documented in full on the Sandbox 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.

handle.snapshot()

snapshot(name: string): Promise<Snapshot>

Snapshot this sandbox under a bare name in the default snapshots directory (~/.microsandbox/snapshots/<name>/). Called on a SandboxHandle. The sandbox must be stopped or crashed; running sandboxes are rejected with a SnapshotSandboxRunning error. To place the artifact elsewhere, use Snapshot.save() / Snapshot.load() or move the self-contained artifact directory.

Parameters

namestring

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

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, resolved under the default snapshots directory (~/.microsandbox/snapshots/<name>/) or under .destDir() when set. The fluent builder is what powers the CLI internally. The source sandbox is set with .fromSandbox(), which is required. See SnapshotBuilder for all setters.

Parameters

namestring

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

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 artifact. Bare names resolve under the default snapshots directory; anything else is treated as a path. Cheap metadata validation only; it does not read the upper file. Use verify() for content checks.

Parameters

pathOrNamestring

Bare name (resolved under the default snapshots dir) or filesystem 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 an indexed snapshot by digest, name, or path. Returns a lightweight SnapshotHandle backed by the local index row.

Parameters

nameOrDigeststring

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

Returns

Promise<SnapshotHandle>

Index-backed handle.

Snapshot.list()

static list(): Promise<SnapshotHandle[]>

Example

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

List indexed snapshots from the local DB cache.

Returns

Promise<SnapshotHandle[]>

All indexed snapshot handles.

Snapshot.listDir()

static listDir(dir: string): Promise<Snapshot[]>

Walk a directory and parse each subdirectory’s manifest. Does not touch the index, which makes it useful for inspecting external snapshot collections that were never loaded. Skips entries that don’t look like snapshot artifacts.

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

Snapshot.reindex()

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

Example

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

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.

Snapshot.save()

staticasync

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

Bundle a 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.

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

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 is a snapshot artifact on disk. The artifact is a directory containing the snapshot.json descriptor 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(), Snapshot.open(), and handle.snapshot().

snap.path

get path(): string

Path to the artifact directory.

snap.digest

get digest(): string

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

snap.sizeBytes

get sizeBytes(): bigint

Apparent size of the captured upper layer in bytes (sparse on disk).

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

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 backed by an index row. Values are snapshotted from the index at construction time; call Snapshot.get() again for a fresh reading if needed. Handles from Snapshot.list() are read-only and throw on open() / remove(); fetch a live handle via Snapshot.get() for those 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`	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>`	Open and metadata-validate the underlying artifact.
`remove(opts?)`	`Promise<void>`	Remove the artifact and its index row; refuses on children unless `force`.

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

SaveOpts interface

Bundle options for Snapshot.save(). All fields default to false.

Used by Snapshot.save()

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

​Capture and boot

​.fromSnapshot()

​handle.snapshot()

​Snapshot static methods

​Snapshot.builder()

​Snapshot.open()

​Snapshot.get()

​Snapshot.list()

​Snapshot.listDir()

​Snapshot.remove()

​Snapshot.reindex()

​Snapshot.save()

​Snapshot.load()

​Snapshot instance members

​snap.path

​snap.digest

​snap.sizeBytes

​snap.imageRef

​snap.imageManifestDigest

​snap.format

​snap.scope

​snap.fstype

​snap.parent

​snap.createdAt

​snap.labels

​snap.sourceSandbox

​snap.verify()

​SnapshotBuilder

​.fromSandbox()

​.destDir()

​.label()

​.force()

​.recordIntegrity()

​.resumable()

​.create()

​Types

​SnapshotHandle class

​SaveOpts interface

​SnapshotScope type

​SnapshotVerifyReport union

Capture and boot

.fromSnapshot()

handle.snapshot()

Snapshot static methods

Snapshot.builder()

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.listDir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Snapshot.load()

Snapshot instance members

snap.path

snap.digest

snap.sizeBytes

snap.imageRef

snap.imageManifestDigest

snap.format

snap.scope

snap.fstype

snap.parent

snap.createdAt

snap.labels

snap.sourceSandbox

snap.verify()

SnapshotBuilder

.fromSandbox()

.destDir()

.label()

.force()

.recordIntegrity()

.resumable()

.create()

Types

SnapshotHandle class

SaveOpts interface

SnapshotScope type

SnapshotVerifyReport union