Python 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

Pass guest_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

class

Returned by snapshot() · Snapshot.create() · Snapshot.open() · Snapshot.list_dir() · handle.open()

Create, open, and manage snapshots. See properties for returned metadata.

Snapshot.create()

@staticmethod
async def create(
    name: str = "",
    *,
    from_sandbox: str,
    group: str | None = None,
    dest_dir: str | os.PathLike[str] | None = None,
    labels: dict[str, str] | None = None,
    force: bool = False,
    record_integrity: bool = False,
    full: bool = False,
    guest_flush: GuestFlush | None = None,
) -> Snapshot

Create a disk snapshot, or set 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

namestr

Snapshot member name; generated when omitted.

from_sandboxstr

Name of the source sandbox. Local disk capture supports running, paused, stopped, and crashed sources. Cloud requires a stopped persistent source. Required.

dest_dirstr | os.PathLike[str] | None

Parent directory containing snapshot groups. Defaults to the snapshots directory.

labelsdict[str, str] | None

User-supplied local labels stored outside the identity-bearing descriptor.

forcebool

Must remain False 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_integritybool

Record an integrity hash in the manifest so the artifact can be verified later. Default False.

fullbool

Local-only when True: 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 | None

Guest writeback policy. Omitted selects AUTO; see guest writeback.

Returns

Snapshot

The captured snapshot.

Example

snap = await Snapshot.create(
    "deps",
    from_sandbox="baseline",
    labels={"stage": "post-deps"},
    record_integrity=True,
)

Snapshot.create_archive()

@staticmethod
async def create_archive(
    name: str,
    archive: str | os.PathLike[str],
    *,
    from_sandbox: str,
    group: str | None = None,
    labels: dict[str, str] | None = None,
    force: bool = False,
    record_integrity: bool = False,
    full: bool = False,
    plain_tar: bool = False,
    guest_flush: GuestFlush | None = None,
) -> SnapshotArchive

Capture directly into an archive without installing a local snapshot.

archive = await Snapshot.create_archive(
    "deps",
    "/tmp/deps.msb",
    from_sandbox="baseline",
)

Snapshot.open()

@staticmethod
async def open(path_or_name: str) -> Snapshot

Example

snap = await Snapshot.open("baseline:deps")
print(snap.image_ref)

Open an existing artifact by group head, group:member, or path. This validates metadata without reading the full upper file. Use verify() for content checks.

Parameters

path_or_namestr

Group head, group:member, or artifact directory path.

Returns

Snapshot

The opened snapshot.

Snapshot.get()

@staticmethod
async def get(name_or_digest: str) -> SnapshotHandle

Example

h = await Snapshot.get("baseline:deps")
print(h.digest)

Look up a handle by group head, group:member, stable snapshot ID, descriptor digest, or artifact path. Global IDs and digests must resolve unambiguously.

Parameters

name_or_digeststr

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

Returns

SnapshotHandle

Lightweight handle returned by the active backend.

Snapshot.list()

@staticmethod
async def list() -> list[SnapshotHandle]

Example

for h in await Snapshot.list():
    print(h.name, h.digest)

List snapshots visible through the active backend. Local uses its index; cloud lists managed snapshots. Host-volume artifacts are opened explicitly by reference.

Returns

list[SnapshotHandle]

Indexed snapshot handles.

Snapshot.list_dir()

@staticmethod
async def list_dir(dir: str | os.PathLike) -> list[Snapshot]

Walk a local directory and parse each subdirectory’s manifest. Does not touch the local index, useful for inspecting external snapshot collections. Skips entries that don’t look like snapshot artifacts. Cloud raises UnsupportedError.

Parameters

dirstr | os.PathLike

Directory to scan for artifacts.

Returns

list[Snapshot]

One snapshot per valid artifact directory.

Snapshot.remove()

@staticmethod
async def remove(path_or_name: str, *, force: bool = False) -> None

Example

await Snapshot.remove("baseline:deps", force=True)

Remove a snapshot through the active backend. Locally, removal also updates the index and refuses indexed children unless force=True.

Parameters

path_or_namestr

Group head, group:member, or artifact path.

forcebool

Remove even if the snapshot has indexed children. Default False.

Snapshot.reindex()

@staticmethod
async def reindex(dir: str | os.PathLike | None = None) -> int

Example

count = await Snapshot.reindex()
print(f"indexed {count} snapshots")

Walk dir (default: configured snapshots dir) and rebuild the local index. Returns the number of artifacts indexed. Cloud raises UnsupportedError.

Parameters

dirstr | os.PathLike | None

Directory to scan. Default: the configured snapshots directory.

Returns

int

Number of artifacts indexed.

Snapshot.save()

staticasync

@staticmethod
async def save(
    name_or_path: str,
    out: str | os.PathLike,
    *,
    with_parents: bool = False,
    with_image: bool = False,
    plain_tar: bool = False,
    since: str | None = None,
    last_layers: int | None = None,
) -> None

Example

await Snapshot.save(
    "baseline:deps",
    "/tmp/deps.msb",
    with_parents=True,
)

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

Group head or group:member or artifact path to save.

outstr | os.PathLike

Output archive path.

with_parentsbool

Include the snapshot’s parent chain. Default False.

with_imagebool

Include the pinned base image. Default False.

plain_tarbool

Write an uncompressed .tar instead of .msb. Default False.

Example

await Snapshot.save(
    "baseline:deps",
    "/tmp/deps.msb",
    with_parents=True,
)

Snapshot.load()

staticasync

@staticmethod
async def load(
    archive: str | os.PathLike,
    *,
    dest: str | os.PathLike | None = None,
    base: str | None = None,
    group: str | None = None,
    set_head: bool = False,
) -> SnapshotHandle

Unpack a snapshot archive (.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

Archive path (.msb or .tar).

deststr | os.PathLike | None

Destination directory. Default: the configured snapshots directory.

Returns

SnapshotHandle

Handle to the loaded snapshot.

Example

h = await Snapshot.load("/tmp/deps.msb")
print(h.path)

Snapshot.load_many()

async def load_many(
    archives: Sequence[str | os.PathLike[str]],
    *,
    dest: str | os.PathLike[str] | None = None,
    base: str | None = None,
    group: str | None = None,
    set_head: bool = False,
) -> list[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.group_head()

async def group_head(selector: str) -> dict[str, str | bool | None]

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 load() and load_many().

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

Snapshot methods

snap.save_to()

async def save_to(
    self,
    out: str | os.PathLike,
    *,
    with_parents: bool = False,
    with_image: bool = False,
    plain_tar: bool = False,
    since: str | None = None,
    last_layers: int | None = None,
) -> None

Bundle this snapshot through the backend retained when it was created or opened. This avoids resolving its reference through a possibly different current default backend. Cloud raises UnsupportedError.

Example

await snap.save_to("/tmp/deps.tar.zst", with_image=True)

snap.copy_to()

def copy_to(self, output_archive_path: str | os.PathLike) -> SnapshotCopyBuilder

Create a new archive from this snapshot’s disk data while replacing its labels and integrity metadata. The source snapshot is unchanged. Cloud raises UnsupportedError when save() is awaited.

Example

await (
    snap.copy_to("/tmp/baseline-copy.tar.zst")
    .labels({"environment": "test"})
    .record_integrity(True)
    .save()
)

snap.verify()

async def verify(self) -> dict[str, Any]

Example

report = await snap.verify()
if report["upper"]["kind"] == "verified":
    print(f"hash matches: {report['upper']['digest']}")
else:
    print("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 checkpoint={"kind": "verified", "root": ...} in the report.

Returns

dict[str, Any]

Verification report. The upper.kind field is “not_recorded” when no integrity hash was stored, or “verified” with the recomputed digest.

The report shape:

{
    "digest": "sha256:...",
    "path": "/path/to/artifact",
    "upper": {"kind": "not_recorded"}                            # no integrity recorded
        | {"kind": "verified", "algorithm": "...", "digest": "sha256:..."},
}

SnapshotHandle methods

handle.open()

async def open(self) -> Snapshot

Example

h = await Snapshot.get("baseline:deps")
snap = await h.open()
print(snap.fstype)

Load the full Snapshot metadata for this handle. Metadata-validated only; does not read the upper file.

Returns

Snapshot

The opened snapshot.

handle.remove()

async def remove(self, *, force: bool = False) -> None

Example

h = await Snapshot.get("baseline:deps")
await h.remove(force=False)

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

Parameters

forcebool

Remove even if the snapshot has indexed children. Default False.

handle.save_to()

async def save_to(
    self,
    out: str | os.PathLike,
    *,
    with_parents: bool = False,
    with_image: bool = False,
    plain_tar: bool = False,
    since: str | None = None,
    last_layers: int | None = None,
) -> None

Bundle the referenced snapshot through the backend retained by the handle. Cloud raises UnsupportedError.

SandboxHandle

handle.snapshot()

async def snapshot(self, name: str) -> Snapshot

Snapshot this sandbox into its default group with the given member name. 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. Called on a SandboxHandle, obtained from Sandbox.get().

Parameters

namestr

Member name within the source sandbox’s group.

Returns

Snapshot

The captured snapshot.

Example

handle = await Sandbox.get("baseline")
snap = await handle.snapshot("deps")
print(snap.digest)

Restore

Restore into a new detached sandbox. Disk boots fresh; full resumes execution. See restore examples and progress.

Example

child = await Sandbox.restore("api:baseline", name="api-restored", cow_memory=True)

Control	Purpose
`cow_memory=True`	Share unchanged full-snapshot memory.
`forked=True`	Deprecated alias for the same CoW memory policy; see migration notes.
`disk_only=True`	Boot only the saved disk.
`snapshot_base`	Supply an archive dependency.
`Sandbox.restore()`	Return the restored sandbox.
`Sandbox.restore_with_progress()`	Return a `PullSession`; await its result.

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 allow_missing_resources=True 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.
`network_policy`	Replace host traffic filtering; guest DNS and TLS settings stay unchanged.
`max_connections`	Concurrent TCP limit; zero means unlimited.
`disable_network`	Remove the NIC. Rejected for full snapshots that captured one.
`security`	Guest security profile. Disk boot only, including an explicit default profile.
`max_duration, idle_timeout`	Lifetime and idle limits. Omitted means unlimited; zero expires immediately.
`volumes, captured_volumes`	Map host volumes or select captured private volumes.
`ports`	Bind destination TCP or UDP ports.
`vsock`	Bind destination vsock endpoints.
`user, log_level`	Default user for new execs and host runtime log level.
`dangerously_inherit_resources`	Explicitly inherit host resources. Disabled by default.
`allow_missing_resources=True`	Allow unavailable external filesystems or additional disks, with warnings. Full restore otherwise requires their bindings.
`external_mount_policy`	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, not Network. captured_volumes contains guest paths.

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.
`root_disk_only`	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.
`dry_run`	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 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

class

Returned by snapshot() · Snapshot.create() · Snapshot.open() · Snapshot.list_dir() · handle.open()

A fully parsed backend-neutral snapshot. Properties are read-only attributes.

Property / Method	Type	Description
`id`	`str`	Stable opaque snapshot identity
`path`	`str`	Local artifact directory; raises `UnsupportedError` on cloud
`reference`	`str`	Stable backend-relative restore reference
`reference_kind`	`Literal["id", "path"]`	How the selected backend resolves the reference
`digest`	`str`	Canonical descriptor digest (`sha256:hex`), separate from the stable ID
`size_bytes`	`int \| None`	Backend-reported stored payload size in bytes
`image_ref`	`str`	Image reference the snapshot was taken from
`image_manifest_digest`	`str`	OCI manifest digest of the pinned image
`state_kind`	`SnapshotStateKind`	File-backed or checkpoint-backed state
`format`	`SnapshotFormat` `\| None`	On-disk format for file-backed state
`scope`	`SnapshotScope`	Captured state scope
`fstype`	`str \| None`	Filesystem type for file-backed state (e.g. `"ext4"`)
`checkpoint_id`	`str \| None`	Checkpoint identifier for checkpoint-backed state
`checkpoint_manifest_digest`	`str \| None`	Checkpoint manifest digest for checkpoint-backed state
`parent`	`str \| None`	Parent snapshot’s digest, or `None` for a root
`created_at`	`str`	RFC 3339 timestamp
`labels`	`dict[str, str]`	User-supplied labels
`source_sandbox`	`str \| None`	Best-effort source-sandbox name
`save_to(...)`	`Awaitable[None]`	Bundle through the backend retained by this snapshot
`copy_to(path)`	`SnapshotCopyBuilder`	Configure a copied archive with replacement metadata
`verify()`	`Awaitable[dict[str, Any]]`	Recompute and check the upper-layer integrity hash. See `verify()`

SnapshotCopyBuilder

Returned by Snapshot.copy_to(). Setters mutate the builder and return it so calls can be chained.

Method	Returns	Description
`labels(dict[str, str])`	`SnapshotCopyBuilder`	Replace all labels in the copied manifest
`record_integrity(bool)`	`SnapshotCopyBuilder`	Compute integrity when true, or omit it when false
`save()`	`Awaitable[None]`	Write the configured archive

SnapshotHandle

class

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

Lightweight handle returned by the active backend. Properties are read-only.

Property / Method	Type	Description
`id`	`str`	Stable opaque snapshot identity
`path`	`str`	Local artifact directory; raises `UnsupportedError` on cloud
`digest`	`str`	Canonical descriptor digest, separate from the stable ID
`name`	`str \| None`	Convenience alias
`parent_digest`	`str \| None`	Parent snapshot digest, or `None` for a root
`image_ref`	`str`	Image the snapshot was taken from
`state_kind`	`SnapshotStateKind`	File-backed or checkpoint-backed state
`format`	`SnapshotFormat` `\| None`	On-disk format for file-backed state
`scope`	`SnapshotScope`	Captured state scope
`fstype`	`str \| None`	Filesystem type for file-backed state
`checkpoint_manifest_digest`	`str \| None`	Checkpoint manifest digest for checkpoint-backed state
`size_bytes`	`int \| None`	Backend-reported stored payload size, when known
`locality`	`str`	Artifact locality reported by the index
`availability`	`str`	Artifact availability reported by the index
`migration_state`	`str`	Current migration state
`migration_error_code`	`str \| None`	Migration error code, when migration failed
`created_at`	`float`	ms since Unix epoch
`reference`	`str`	Stable backend-relative restore reference
`reference_kind`	`Literal["id", "path"]`	How the selected backend resolves the reference
`open()`	`Awaitable[Snapshot]`	Load full metadata. See `open()`
`remove(force=False)`	`Awaitable[None]`	Delete the artifact and its index row. See `remove()`
`save_to(...)`	`Awaitable[None]`	Bundle through the backend retained by this handle

SnapshotStateKind

Returned by Snapshot.state_kind · SnapshotHandle.state_kind

Snapshot state representation.

Member	Value	Description
`SnapshotStateKind.FILE`	`"file"`	File-backed upper-layer state
`SnapshotStateKind.CHECKPOINT`	`"checkpoint"`	Checkpoint-manifest-backed state

SnapshotFormat

Returned by Snapshot.format · SnapshotHandle.format

On-disk format for file-backed snapshot state.

Member	Value	Description
`SnapshotFormat.RAW`	`"raw"`	Raw disk image
`SnapshotFormat.QCOW2`	`"qcow2"`	QEMU copy-on-write v2 image

SnapshotScope

Returned by Snapshot.scope · SnapshotHandle.scope

Captured snapshot state scope.

Member	Value	Description
`SnapshotScope.DISK`	`"disk"`	Disk-only state
`SnapshotScope.FULL`	`"full"`	Disk, memory, and device state

from microsandbox import SnapshotFormat, SnapshotScope, SnapshotStateKind

assert snapshot.state_kind is SnapshotStateKind.FILE
assert snapshot.format is SnapshotFormat.RAW
assert snapshot.scope is SnapshotScope.DISK

Getting Started

SDKs

CLI

Snapshots

Guest writeback

Snapshot

Snapshot.create()

Snapshot.create_archive()

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.list_dir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Snapshot.load()

Snapshot.load_many()

Snapshot.group_head()

Import options

Snapshot methods

snap.save_to()

snap.copy_to()

snap.verify()

SnapshotHandle methods

handle.open()

handle.remove()

handle.save_to()

SandboxHandle

handle.snapshot()

Restore

Compaction

Types

Snapshot properties

SnapshotCopyBuilder

SnapshotHandle

SnapshotStateKind

SnapshotFormat

SnapshotScope

​Guest writeback

​Snapshot

​Snapshot.create()

​Snapshot.create_archive()

​Snapshot.open()

​Snapshot.get()

​Snapshot.list()

​Snapshot.list_dir()

​Snapshot.remove()

​Snapshot.reindex()

​Snapshot.save()

​Snapshot.load()

​Snapshot.load_many()

​Snapshot.group_head()

​Import options

​Snapshot methods

​snap.save_to()

​snap.copy_to()

​snap.verify()

​SnapshotHandle methods

​handle.open()

​handle.remove()

​handle.save_to()

​SandboxHandle

​handle.snapshot()

​Restore

​Compaction

​Types

​Snapshot properties

​SnapshotCopyBuilder

​SnapshotHandle

​SnapshotStateKind

​SnapshotFormat

​SnapshotScope

Guest writeback

Snapshot

Snapshot.create()

Snapshot.create_archive()

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.list_dir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Snapshot.load()

Snapshot.load_many()

Snapshot.group_head()

Import options

Snapshot methods

snap.save_to()

snap.copy_to()

snap.verify()

SnapshotHandle methods

handle.open()

handle.remove()

handle.save_to()

SandboxHandle

handle.snapshot()

Restore

Compaction

Types

Snapshot properties

SnapshotCopyBuilder

SnapshotHandle

SnapshotStateKind

SnapshotFormat

SnapshotScope