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()
fromSandbox(); see SnapshotBuilder for options.
Parameters
namestringReturns
Example
Example
builder.createArchive()
Example
Example
Snapshot.open()
Example
Example
group:member, or path. Cheap metadata validation only; it does not read the upper file. Use verify() for content checks.
Parameters
pathOrNamestringgroup:member selector or filesystem path.Returns
Snapshot.get()
Example
Example
SnapshotHandle.
Parameters
nameOrDigeststringReturns
Snapshot.list()
Example
Example
Returns
Snapshot.listDir()
UnsupportedError.
Parameters
dirstringReturns
Snapshot.remove()
Example
Example
force is set. A group’s head cannot be removed while other members remain, even with force; select another head first.
Parameters
pathOrNamestringgroup:member, unambiguous snapshot ID or digest, or artifact path.opts.forcebooleanfalse.Snapshot.reindex()
Example
Example
UnsupportedError.
Parameters
dirstringReturns
Snapshot.save()
.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
nameOrPathstringgroup:member, or artifact path to bundle.outstringoptsSaveOptsfalse.Example
Example
Snapshot.load()
.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
archivestringdeststringReturns
Example
Example
Snapshot.loadWithOptions()
Snapshot.loadMany()
Snapshot.groupHead()
group:member. Returns the group, previous and current snapshot IDs, reason, and whether the head changed. See group selection.
Import options
Options forLoadOpts.
SandboxHandle
handle.snapshot()
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
namestringReturns
Example
Example
Snapshot instance members
ASnapshot 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()
UnsupportedError.
Example
Example
snap.copyTo()
UnsupportedError when save() is awaited.
Example
Example
snap.verify()
Example
Example
report.checkpoint.
Returns
SnapshotHandle
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()
Snapshot.list()); fetch a live handle via Snapshot.get() first.
snapshotHandle.remove()
force is set. Throws if this handle is read-only.
Example
Example
snapshotHandle.reference
string
Backend-relative snapshot reference.
snapshotHandle.referenceKind
"id" \| "path"
How the backend resolves the reference.
snapshotHandle.saveTo()
Snapshot.list() are metadata-only; fetch a live handle
with Snapshot.get() first. Cloud returns UnsupportedError.
SnapshotBuilder
Fluent builder for a snapshot, returned bySnapshot.builder(name). Every setter mutates in place and returns this, so calls chain. The source sandbox is required: call .fromSandbox() before .create().
.fromSandbox()
.create() fails without it.
Parameters
sourceSandboxstring.group()
.destDir()
Parameters
destDirstring.label()
key=value label to the snapshot manifest. May be called repeatedly.
Parameters
keystringvaluestring.force()
.recordIntegrity()
snapshot.full()
.guestFlush()
"auto". See SDK usage.
.create()
Example
Example
Returns
SnapshotCopyBuilder
Returned bysnapshot.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()
Example
Example
forkMany()
Example
Example
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.Example
Example
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.
Destination options
Destination options
NetworkPolicy or NetworkPolicyBuilder. Use v => v.captured() for a private captured volume.restore.volume()
v => v.captured() to select its captured private volume.
Example
Example
restore.allowMissingResources()
Compaction
Compact a local sandbox’s root or owned disks. See compaction for examples and recovery requirements.Options and results
Options and results
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 forSnapshot.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 ofsnap.verify(). Checkpoint snapshots add checkpoint: { kind: "verified", root: string }; the existing upper projection stays intact for disk-snapshot compatibility.
Returned by snap.verify()