Snapshots - microsandbox

Create and manage disk-only snapshots of stopped sandboxes. See Snapshots for usage and lifecycle concepts.

SandboxBuilder

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

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

SandboxHandle

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

Instance properties

A Snapshot is a snapshot artifact on disk. The artifact directory is the source of truth; the local database index is a rebuildable cache.

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.

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. Structural and archive-entry checks run during import; recorded payload integrity is preserved for explicit verify(). 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);

Instance methods

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.

Returns

Promise<SnapshotVerifyReport>

Verification result.

SnapshotHandle

class

A metadata and lifecycle handle for an existing snapshot.

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

snapshotHandle.digest

string Manifest digest (sha256:hex), the canonical identity.

snapshotHandle.name

string \| null Convenience name; null for digest-only entries.

snapshotHandle.parentDigest

string \| null Parent snapshot’s manifest digest, or null for a root.

snapshotHandle.scope

SnapshotScope Snapshot payload scope ("disk" today).

snapshotHandle.imageRef

string Image reference the snapshot was taken from.

snapshotHandle.format

"raw" \| "qcow2" On-disk format of the upper layer.

snapshotHandle.sizeBytes

bigint \| null Apparent size of the upper file at index time.

snapshotHandle.createdAt

Date Snapshot creation time (from manifest).

snapshotHandle.path

string Local artifact directory path.

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

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

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

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

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

snapshot.force()

force(): this

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

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

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

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

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

​SandboxBuilder

​sandbox.fromSnapshot()

​SandboxHandle

​handle.snapshot()

​Snapshot

​snap.path

​snap.digest

​snap.sizeBytes

​snap.imageRef

​snap.imageManifestDigest

​snap.format

​snap.scope

​snap.fstype

​snap.parent

​snap.createdAt

​snap.labels

​snap.sourceSandbox

​Snapshot.builder()

​Snapshot.open()

​Snapshot.get()

​Snapshot.list()

​Snapshot.listDir()

​Snapshot.remove()

​Snapshot.reindex()

​Snapshot.save()

​Snapshot.load()

​snap.verify()

​SnapshotHandle

​snapshotHandle.digest

​snapshotHandle.name

​snapshotHandle.parentDigest

​snapshotHandle.scope

​snapshotHandle.imageRef

​snapshotHandle.format

​snapshotHandle.sizeBytes

​snapshotHandle.createdAt

​snapshotHandle.path

​snapshotHandle.open()

​snapshotHandle.remove()

​SnapshotBuilder

​snapshot.fromSandbox()

​snapshot.destDir()

​snapshot.label()

​snapshot.force()

​snapshot.recordIntegrity()

​snapshot.resumable()

​snapshot.create()

​Types

​SaveOpts interface

​SnapshotScope type

​SnapshotVerifyReport union

SandboxBuilder

sandbox.fromSnapshot()

SandboxHandle

handle.snapshot()

Snapshot

snap.path

snap.digest

snap.sizeBytes

snap.imageRef

snap.imageManifestDigest

snap.format

snap.scope

snap.fstype

snap.parent

snap.createdAt

snap.labels

snap.sourceSandbox

Snapshot.builder()

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.listDir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Snapshot.load()

snap.verify()

SnapshotHandle

snapshotHandle.digest

snapshotHandle.name

snapshotHandle.parentDigest

snapshotHandle.scope

snapshotHandle.imageRef

snapshotHandle.format

snapshotHandle.sizeBytes

snapshotHandle.createdAt

snapshotHandle.path

snapshotHandle.open()

snapshotHandle.remove()

SnapshotBuilder

snapshot.fromSandbox()

snapshot.destDir()

snapshot.label()

snapshot.force()

snapshot.recordIntegrity()

snapshot.resumable()

snapshot.create()

Types

SaveOpts interface

SnapshotScope type

SnapshotVerifyReport union