TypeScript SDK Snapshots reference

See the snapshot guide 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.

Snapshot

A snapshot retains the backend that created or opened it.

Static methods

Snapshot.builder()

static builder(name?: string): SnapshotBuilder

Configure a snapshot. Set the required source with fromSandbox(); see SnapshotBuilder for options.

Parameters

namestring

Member name within its group; generated when omitted.

Returns

SnapshotBuilder

Builder for configuring the snapshot.

Example

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

builder.createArchive()

createArchive(out: string, plainTar?: boolean): Promise<SnapshotArchive>

Capture directly into an archive without installing a local snapshot.

Example

const archive = await Snapshot.builder("deps")
  .fromSandbox("baseline")
  .createArchive("/tmp/deps.msb");

Snapshot.open()

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

Example

const snap = await Snapshot.open("baseline:deps");
console.log(snap.digest);

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

Parameters

pathOrNamestring

Group head or group:member selector or filesystem path.

Returns

Promise<Snapshot>

The opened snapshot.

Snapshot.get()

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

Example

const h = await Snapshot.get("baseline:deps");
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("baseline:deps", { force: true });

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.

Parameters

pathOrNamestring

Group head, group:member, unambiguous snapshot ID or digest, or artifact path.

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 snapshot into a .msb 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

Group head, group:member, or artifact path to bundle.

outstring

Output archive path.

optsSaveOpts

Bundling options. All fields default to false.

Example

await Snapshot.save("baseline:deps", "./baseline.msb", {
  withImage: true,
});

Snapshot.load()

staticasync

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(). 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.msb");
console.log("loaded", h.digest);

Snapshot.loadWithOptions()

static loadWithOptions(archive: string, opts?: LoadOpts): Promise<SnapshotHandle>

Import an archive with an explicit dependency base or destination group. See import options.

Snapshot.loadMany()

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.

Snapshot.groupHead()

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.

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.

SandboxHandle

handle.snapshot()

snapshot(name: string): Promise<Snapshot>

Snapshot this sandbox into its default group with the given member name. Called on a SandboxHandle. Local live disk captures preserve the source’s running or paused state. Cloud requires a stopped persistent source. Use the returned artifact path or sandbox:member to open it later.

Parameters

namestring

Member name within the source sandbox’s group.

Returns

Promise<Snapshot>

The created snapshot artifact.

Example

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

Snapshot instance members

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

Field	Type	Description
`id`	`string`	Stable opaque `snap_...` identity, separate from the descriptor digest.
`path`	`string`	Local artifact directory. Throws `UnsupportedError` for cloud snapshots; use the snapshot object or its typed reference for backend-neutral operations.
`reference`	`string`	Stable backend-relative value. Pass the snapshot object to `Sandbox.restore(snapshot)` to preserve both this value and its reference kind.
`referenceKind`	`"id" \| "path"`	How the selected backend resolves `reference`. Most callers can pass the snapshot object directly and never inspect this value.
`digest`	`string`	Canonical descriptor digest (`sha256:hex`), separate from the stable snapshot ID.
`sizeBytes`	`bigint \| null`	Backend-reported stored payload size in bytes, or `null` when unavailable.
`imageRef`	`string`	Image reference the snapshot was taken from.
`imageManifestDigest`	`string`	OCI manifest digest of the pinned image.
`format`	`"raw" \| "qcow2" \| null`	On-disk format of the upper layer.
`scope`	`SnapshotScope`	Snapshot scope: `"disk"` for a disk-only snapshot or `"full"` for disk plus VM execution state. See `SnapshotScope`.
`fstype`	`string \| null`	Filesystem type inside the upper (e.g. `"ext4"`).
`parent`	`string \| null`	Manifest digest of the parent snapshot, or `null` for a root.
`createdAt`	`string`	RFC 3339 timestamp when the snapshot was created.
`labels`	`ReadonlyArray<readonly [string, string]>`	User-supplied labels (sorted by key in canonical form), as `[key, value]` pairs.
`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.

Example

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

snap.copyTo()

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.

Example

await snap
  .copyTo("./baseline-copy.tar.zst")
  .labels({ environment: "test" })
  .recordIntegrity(true)
  .save();

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");
}

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.

Returns

Promise<SnapshotVerifyReport>

Verification result.

SnapshotHandle

class

A metadata and lifecycle handle for an existing snapshot.

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

Field	Type	Description
`digest`	`string`	Descriptor digest (`sha256:hex`), separate from the stable snapshot ID.
`name`	`string \| null`	Member name within its group, or `null` when no alias is recorded.
`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.

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

Example

const h = await Snapshot.get("baseline:deps");
const snap = await h.open();          // metadata-validated
await h.remove({ force: false });     // refuse if it has children

Field	Type	Description
`reference`	`string`	Backend-relative snapshot reference.
`referenceKind`	`"id" \| "path"`	How the backend resolves the reference.

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.

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 source sandbox. Local disk capture supports running, paused, stopped, and crashed sources. Cloud requires a stopped persistent source.

.group()

group(name: string): this

Set the local snapshot group. Defaults to the source sandbox’s name. Direct archive capture does not accept a group.

.destDir()

builder

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.

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 direct archive output file. Installed group members are immutable, so installed creation rejects this option.

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

builder

full(): this

Local-only: capture disk, memory, and execution state. The source must be running or paused and returns to that state after capture.

.guestFlush()

guestFlush(policy: GuestFlush): this

Select guest writeback before capture. GuestFlush is "auto" | "required" | "skip"; defaults to "auto". See guest writeback.

.create()

create(): Promise<Snapshot>

Example

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

Capture the configured snapshot and return the resulting artifact.

Returns

Promise<Snapshot>

The created snapshot artifact.

SnapshotCopyBuilder

Returned by snapshot.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 and progress.

Example

const child = await Sandbox.restore("api:baseline")
  .name("api-restored")
  .cowMemory()
  .restore();

Control	Purpose
`cowMemory()`	Share unchanged full-snapshot memory.
`.forked()`	Deprecated alias for the same CoW memory policy; see migration notes.
`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.

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.

Compaction

Compact a local sandbox’s root or owned disks. See compaction for examples and recovery requirements.

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.

Types

SaveOpts interface

Bundle options for Snapshot.save() and instance saveTo() methods. Boolean fields default to false; selective-export fields are omitted by default.

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

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 type

Scope of what a snapshot captures: "disk" for filesystem state or "full" for disk plus VM execution state.

Returned by snap.scope · SnapshotHandle.scope

type SnapshotScope = "disk" | "full";

SnapshotVerifyReport union

Result of snap.verify(). Checkpoint snapshots add checkpoint: { kind: "verified", root: string }; the existing upper projection stays intact for disk-snapshot compatibility.

Returned by snap.verify()

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

​Guest writeback

​Snapshot

​Snapshot.builder()

​builder.createArchive()

​Snapshot.open()

​Snapshot.get()

​Snapshot.list()

​Snapshot.listDir()

​Snapshot.remove()

​Snapshot.reindex()

​Snapshot.save()

​Snapshot.load()

​Snapshot.loadWithOptions()

​Snapshot.loadMany()

​Snapshot.groupHead()

​Import options

​SandboxHandle

​handle.snapshot()

​Snapshot instance members

​snap.saveTo()

​snap.copyTo()

​snap.verify()

​SnapshotHandle

​snapshotHandle.open()

​snapshotHandle.remove()

​snapshotHandle.saveTo()

​SnapshotBuilder

​.fromSandbox()

​.group()

​.destDir()

​.label()

​.force()

​.recordIntegrity()

​snapshot.full()

​.guestFlush()

​.create()

​SnapshotCopyBuilder

​RestoreBuilder

​Compaction

​Types

​SaveOpts interface

​SnapshotScope type

​SnapshotVerifyReport union

Guest writeback

Snapshot

Snapshot.builder()

builder.createArchive()

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.listDir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Snapshot.load()

Snapshot.loadWithOptions()

Snapshot.loadMany()

Snapshot.groupHead()

Import options

SandboxHandle

handle.snapshot()

Snapshot instance members

snap.saveTo()

snap.copyTo()

snap.verify()

SnapshotHandle

snapshotHandle.open()

snapshotHandle.remove()

snapshotHandle.saveTo()

SnapshotBuilder

.fromSandbox()

.group()

.destDir()

.label()

.force()

.recordIntegrity()

snapshot.full()

.guestFlush()

.create()

SnapshotCopyBuilder

RestoreBuilder

Compaction

Types

SaveOpts interface

SnapshotScope type

SnapshotVerifyReport union