group:member, or artifact path.
Guest writeback
Passguest_flush=GuestFlush.REQUIRED to Snapshot.create, Snapshot.create_archive, source.fork, source.fork_many, or source.pause. Import GuestFlush from microsandbox.
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
Returned by snapshot() · Snapshot.create() · Snapshot.open() · Snapshot.list_dir() · handle.open()
Create, open, and manage snapshots. See properties for returned metadata.Snapshot.create()
full=True to include memory and execution state. name identifies a member within group; an omitted name is generated and an omitted group uses the source sandbox’s name. dest_dir selects the parent directory containing the group. from_sandbox names the sandbox to capture and is required.
Parameters
namestrfrom_sandboxstrdest_dirstr | os.PathLike[str] | Nonelabelsdict[str, str] | NoneforceboolFalse for installed group members. Since v0.7, True raises InvalidConfigError even when the name does not exist. Use a new or generated member name, or explicitly remove the existing member before recreating it. See the v0.6 upgrade example. Direct archive capture supports overwriting its output file.record_integrityboolFalse.fullboolTrue: capture disk, memory, execution, and device state from a running or paused sandbox. Default False captures disk state; locally, the source can be running, paused, stopped, or crashed. Cloud requires False and a stopped persistent source.guest_flushGuestFlush | NoneAUTO; see guest writeback.Returns
Example
Example
Snapshot.create_archive()
Snapshot.open()
Example
Example
group:member, or path. This validates metadata without reading the full upper file. Use verify() for content checks.
Parameters
path_or_namestrgroup:member, or artifact directory path.Returns
Snapshot.get()
Example
Example
group:member, stable snapshot ID, descriptor digest, or artifact path. Global IDs and digests must resolve unambiguously.
Parameters
name_or_digeststrgroup:member, stable snapshot ID, descriptor digest, or artifact path.Returns
Snapshot.list()
Example
Example
Returns
Snapshot.list_dir()
UnsupportedError.
Parameters
dirstr | os.PathLikeReturns
Snapshot.remove()
Example
Example
force=True.
Parameters
path_or_namestrgroup:member, or artifact path.forceboolFalse.Snapshot.reindex()
Example
Example
dir (default: configured snapshots dir) and rebuild the local index.
Returns the number of artifacts indexed. Cloud raises UnsupportedError.
Parameters
dirstr | os.PathLike | NoneReturns
Snapshot.save()
Example
Example
.msb archive. The existing snapshot manifest is archived as-is; create the snapshot with recorded integrity when the archive will cross a trust boundary.
Parameters
name_or_pathstrgroup:member or artifact path to save.outstr | os.PathLikewith_parentsboolFalse.with_imageboolFalse.plain_tarbool.tar instead of .msb. Default False.Example
Example
Snapshot.load()
.msb or .tar) into the selected or generated group. The returned handle’s group identifies the group and head_update reports the head selection outcome. Structural and archive-entry checks run during import; recorded payload integrity is preserved for explicit verify(). Compression is detected from magic bytes.
Parameters
archivestr | os.PathLike.msb or .tar).deststr | os.PathLike | NoneReturns
Example
Example
Snapshot.load_many()
Snapshot.group_head()
group:member. Returns the group, previous and current snapshot IDs, reason, and whether the head changed. See group selection.
Import options
Options forload() and load_many().
Snapshot methods
snap.save_to()
UnsupportedError.
Example
Example
snap.copy_to()
UnsupportedError when save() is awaited.
Example
Example
snap.verify()
Example
Example
checkpoint={"kind": "verified", "root": ...} in the report.
Returns
upper.kind field is “not_recorded” when no integrity hash was stored, or “verified” with the recomputed digest.SnapshotHandle methods
handle.open()
Example
Example
Snapshot metadata for this handle. Metadata-validated only; does not read the upper file.
Returns
handle.remove()
Example
Example
force=True.
Parameters
forceboolFalse.handle.save_to()
UnsupportedError.
SandboxHandle
handle.snapshot()
sandbox:member to open it later. Called on a SandboxHandle, obtained from Sandbox.get().
Parameters
namestrReturns
Example
Example
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
fork_many()
Example
Example
name, plus a started sandbox or an error; the other field is None. Validation or capture errors raise for the whole call; a child startup error leaves successful siblings running. Stop successful children when finished.
record_integrity records disk hashes. guest_flush defaults to GuestFlush.AUTO; see guest writeback for policy details. volumes rebinds captured disks; forks cannot add new block devices, and batch children cannot share a writable disk image. See fork disk bindings. branch() and branch_many() remain deprecated aliases that emit DeprecationWarning; BranchOutcome aliases ForkOutcome.
Restore
Restore into a new detached sandbox. Disk boots fresh; full resumes execution. See restore examples and progress.Example
Example
allow_missing_resources=True 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, not Network. captured_volumes contains guest paths.restore.volumes
Sandbox.restore() and restore_with_progress(). Map host volumes to guest paths.
Example
Example
restore.captured_volumes
restore.allow_missing_resources
Compaction
Compact a local sandbox’s root or owned disks. See compaction for examples and recovery requirements.Options and results
Options and results
guest_path. materialized_bytes counts copied bytes, not reclaimed space. Times are microseconds: per-disk total_us covers preparation; aggregate total_us also includes switching; pause_us measures the shared VM pause.Types
Snapshot properties
Returned by snapshot() · Snapshot.create() · Snapshot.open() · Snapshot.list_dir() · handle.open()
A fully parsed backend-neutral snapshot. Properties are read-only attributes.SnapshotCopyBuilder
Returned bySnapshot.copy_to(). Setters mutate the builder and
return it so calls can be chained.
SnapshotHandle
Returned by Snapshot.get() · Snapshot.list() · Snapshot.load()
Lightweight handle returned by the active backend. Properties are read-only.SnapshotStateKind
Returned by Snapshot.state_kind · SnapshotHandle.state_kind
Snapshot state representation.SnapshotFormat
Returned by Snapshot.format · SnapshotHandle.format
On-disk format for file-backed snapshot state.SnapshotScope
Returned by Snapshot.scope · SnapshotHandle.scope
Captured snapshot state scope.