Skip to main content
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()

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

Parameters

namestring
Member name within its group; generated when omitted.

Returns

Builder for configuring the snapshot.

builder.createArchive()

Capture directly into an archive without installing a local snapshot.

Snapshot.open()

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

The opened snapshot.

Snapshot.get()

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

Lightweight handle returned by the active backend.

Snapshot.list()

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

Returns

All indexed snapshot handles.

Snapshot.listDir()

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

Parsed snapshots found in the directory.

Snapshot.remove()

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

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
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.
Bundling options. All fields default to false.

Snapshot.load()

staticasync
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

Handle to the loaded snapshot.

Snapshot.loadWithOptions()

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

Snapshot.loadMany()

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

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

The created snapshot artifact.

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

snap.id

string Stable opaque snap_... identity, separate from the descriptor digest.

snap.path

string Local artifact directory. Throws UnsupportedError for cloud snapshots; use the snapshot object or its typed reference for backend-neutral operations.

snap.reference

string Stable backend-relative value. Pass the snapshot object to Sandbox.restore(snapshot) to preserve both this value and its reference kind.

snap.referenceKind

"id" \| "path" How the selected backend resolves reference. Most callers can pass the snapshot object directly and never inspect this value.

snap.digest

string Canonical descriptor digest (sha256:hex), separate from the stable snapshot ID.

snap.sizeBytes

bigint \| null Backend-reported stored payload size in bytes, or null when unavailable.

snap.imageRef

string Image reference the snapshot was taken from.

snap.imageManifestDigest

string OCI manifest digest of the pinned image.

snap.format

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

snap.scope

SnapshotScope Snapshot scope: "disk" for a disk-only snapshot or "full" for disk plus VM execution state. See SnapshotScope.

snap.fstype

string \| null Filesystem type inside the upper (e.g. "ext4").

snap.parent

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

snap.createdAt

string RFC 3339 timestamp when the snapshot was created.

snap.labels

ReadonlyArray<readonly [string, string]> User-supplied labels (sorted by key in canonical form), as [key, value] pairs.

snap.sourceSandbox

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

snap.saveTo()

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.

snap.copyTo()

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.

snap.verify()

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

Verification result.

SnapshotHandle

class
A metadata and lifecycle handle for an existing snapshot.

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

snapshotHandle.digest

string Descriptor digest (sha256:hex), separate from the stable snapshot ID.

snapshotHandle.name

string \| null Member name within its group, or null when no alias is recorded.

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

snapshotHandle.reference

string Backend-relative snapshot reference.

snapshotHandle.referenceKind

"id" \| "path" How the backend resolves the reference.

snapshotHandle.saveTo()

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

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

.destDir()

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

Add a key=value label to the snapshot manifest. May be called repeatedly.

Parameters

keystring
Label key.
valuestring
Label value.

.force()

Overwrite an existing direct archive output file. Installed group members are immutable, so installed creation rejects this option.

.recordIntegrity()

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
Local-only: capture disk, memory, and execution state. The source must be running or paused and returns to that state after capture.

.guestFlush()

Select the guest writeback policy before capture. Defaults to "auto". See SDK usage.

.create()

Capture the configured snapshot and return the resulting artifact.

Returns

The created snapshot artifact.

SnapshotCopyBuilder

Returned by snapshot.copyTo(). Each setter mutates the builder and returns this.

Forking

Fork a running or paused local sandbox to create a child with copy-on-write memory. The source returns to its previous state, and each child needs an unused name. SandboxHandle has the same methods. See the forking guide for backend limits and disk bindings.

fork()

Create one child from the current execution state.

forkMany()

Capture once for all names and return outcomes in input order. Each outcome has name and either a started sandbox or an error. Validation or capture errors reject the whole call; a child startup error leaves successful siblings running. Stop successful children when finished.

ForkOptions

recordIntegrity records disk hashes. guestFlush defaults to "auto". Each volumes key is a captured disk’s guest path; its callback configures the replacement mount. Forks cannot add new block devices, and batch children cannot share a writable disk image. See fork disk bindings. branch(), branchMany(), and BranchOutcome remain deprecated aliases.

RestoreBuilder

Restore into a new detached sandbox. Disk boots fresh; full resumes execution. See restore examples and progress.
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. Restore rejects missing external filesystems (and, for full restore, additional disks) by default. Use allowMissingResources() to resume with unavailable devices (full restore records warnings). This is separate from strict/relaxed validation of supplied mappings; inheritance does not waive missing backing. Root and owned storage remain required.
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.

restore.volume()

Map a host volume to a guest path, or use v => v.captured() to select its captured private volume.

restore.allowMissingResources()

Allow unavailable external filesystems or additional disks. Full restore records warnings; root and owned storage remain required. Disabled by default. This does not relax validation of supplied mappings.

Compaction

Compact a local sandbox’s root or owned disks. See compaction for examples and recovery requirements.
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


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


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