Snapshots - microsandbox

Create and manage disk-only snapshots of stopped sandboxes. See Snapshots for usage and lifecycle concepts.

SandboxHandle

handle.snapshot()

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

Snapshot this sandbox under a bare name in the default snapshots directory (~/.microsandbox/snapshots/<name>/). The sandbox must be stopped or crashed. To place the artifact elsewhere, use Snapshot.save() / Snapshot.load() or move the self-contained artifact directory. Called on a SandboxHandle, obtained from Sandbox.get().

Parameters

namestr

Snapshot name; resolved under the default snapshots directory.

Returns

Snapshot

The captured snapshot.

Example

handle = await Sandbox.get("baseline")
snap = await handle.snapshot("after-pip-install")
print(snap.digest)

Sandbox

Sandbox.create()

@staticmethod
async def create(name: str, *, from_snapshot: str | os.PathLike | None = None, **kwargs) -> Sandbox

Boot a fresh sandbox from a snapshot artifact by passing from_snapshot= as a peer of image=. The two are mutually exclusive: pass exactly one. See Sandbox.create() for the full set of configuration kwargs.

Parameters

namestr

Sandbox name, up to 128 UTF-8 bytes.

from_snapshotstr | os.PathLike | None

Snapshot bare name or artifact path to boot from instead of image=.

Returns

Sandbox

Running sandbox.

Example

# Boot from a snapshot
sb = await Sandbox.create("worker", from_snapshot="after-pip-install")

# Or from an image (existing flow, unchanged)
sb = await Sandbox.create("worker", image="python:3.12")

Snapshot

class

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

A fully-parsed snapshot artifact. Properties are read-only attributes (not async).

snapshot.path

str Path to the artifact directory

snapshot.digest

str Canonical content digest (sha256:hex). The snapshot’s identity

snapshot.size_bytes

int \| None Apparent size of the captured upper layer in bytes (sparse on disk), when recorded

snapshot.image_ref

str Image reference the snapshot was taken from

snapshot.image_manifest_digest

str OCI manifest digest of the pinned image

snapshot.state_kind

SnapshotStateKind File-backed or checkpoint-backed state

snapshot.format

SnapshotFormat \| None On-disk format for file-backed state

snapshot.scope

SnapshotScope Captured state scope

snapshot.fstype

str \| None Filesystem type for file-backed state (e.g. "ext4")

snapshot.checkpoint_id

str \| None Checkpoint identifier for checkpoint-backed state

snapshot.checkpoint_manifest_digest

str \| None Checkpoint manifest digest for checkpoint-backed state

snapshot.parent

str \| None Parent snapshot’s digest, or None for a root

snapshot.created_at

str RFC 3339 timestamp

snapshot.labels

dict[str, str] User-supplied labels

snapshot.source_sandbox

str \| None Best-effort source-sandbox name

Snapshot.create()

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

Create a snapshot from a stopped or crashed sandbox. name is resolved under the default snapshots directory (~/.microsandbox/snapshots/<name>/), or under dest_dir= when given; from_sandbox= names the sandbox to capture and is required.

Parameters

namestr

Bare snapshot name; resolved under the default snapshots directory.

from_sandboxstr

Name of the stopped or crashed sandbox to capture. Required.

dest_dirstr | os.PathLike[str] | None

Parent directory to create the artifact in; the artifact lands at dest_dir/<name>. Defaults to the snapshots directory.

labelsdict[str, str] | None

User-supplied labels stored in the manifest.

forcebool

Overwrite an existing artifact with the same name. Default False.

record_integritybool

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

resumablebool

Request a “resumable” snapshot (disk plus VM state). Accepted, but currently fails with an Unsupported error; resumable snapshots have not landed yet. Default False.

Returns

Snapshot

The captured snapshot.

Example

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

Snapshot.open()

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

Example

snap = await Snapshot.open("after-pip-install")
print(snap.image_ref)

Open an existing artifact by bare name (resolved under the default snapshots directory) or path. Cheap metadata validation only; does not read the upper file. Use verify() for content checks.

Parameters

path_or_namestr

Bare snapshot name 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("after-pip-install")
print(h.digest)

Look up a handle in the local index by name, digest, or path.

Parameters

name_or_digeststr

Snapshot name, digest, or path.

Returns

SnapshotHandle

Lightweight handle backed by an index row.

Snapshot.list()

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

Example

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

List indexed snapshots from the local DB cache.

Returns

list[SnapshotHandle]

Indexed snapshot handles.

Snapshot.list_dir()

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

Walk a directory and parse each subdirectory’s manifest. Does not touch the index, useful for inspecting external snapshot collections (e.g. a mounted volume of artifacts that were never loaded). Skips entries that don’t look like snapshot artifacts.

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("after-pip-install", force=True)

Remove a snapshot artifact and its index row. Refuses if the snapshot has indexed children unless force=True.

Parameters

path_or_namestr

Bare snapshot name 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.

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,
) -> None

Example

await Snapshot.save(
    "after-pip-install",
    "/tmp/after-pip-install.tar.zst",
    with_parents=True,
)

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

Snapshot bare name 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 .tar.zst. Default False.

Move artifacts

Snapshot.load()

staticasync

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

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

archivestr | os.PathLike

Archive path (.tar.zst 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/after-pip-install.tar.zst")
print(h.path)

Inspect

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

Recompute the upper layer’s recorded content integrity and compare against the descriptor. Current BLAKE3 Merkle integrity skips known all-hole subtrees and hashes allocated leaves in batches; released SHA descriptors retain their exact, potentially O(logical size), verifier. Returns not_recorded without reading payload contents when no integrity was stored.

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

class

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

Lightweight handle backed by an index row. Properties are read-only attributes (not async).

handle.digest

str Manifest digest, canonical identity

handle.name

str \| None Convenience alias

handle.parent_digest

str \| None Parent snapshot digest, or None for a root

handle.image_ref

str Image the snapshot was taken from

handle.state_kind

SnapshotStateKind File-backed or checkpoint-backed state

handle.format

SnapshotFormat \| None On-disk format for file-backed state

handle.scope

SnapshotScope Captured state scope

handle.fstype

str \| None Filesystem type for file-backed state

handle.checkpoint_manifest_digest

str \| None Checkpoint manifest digest for checkpoint-backed state

handle.size_bytes

int \| None Apparent upper size at index time

handle.locality

str Artifact locality reported by the index

handle.availability

str Artifact availability reported by the index

handle.migration_state

str Current migration state

handle.migration_error_code

str \| None Migration error code, when migration failed

handle.created_at

float ms since Unix epoch

handle.path

str Local artifact directory path

handle.open()

async def open(self) -> Snapshot

Example

h = await Snapshot.get("after-pip-install")
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("after-pip-install")
await h.remove(force=False)

Remove this snapshot artifact and its index row. Refuses if the snapshot has indexed children unless force=True.

Parameters

forcebool

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

Types

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.RESUMABLE`	`"resumable"`	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

​SandboxHandle

​handle.snapshot()

​Sandbox

​Sandbox.create()

​Snapshot

​snapshot.path

​snapshot.digest

​snapshot.size_bytes

​snapshot.image_ref

​snapshot.image_manifest_digest

​snapshot.state_kind

​snapshot.format

​snapshot.scope

​snapshot.fstype

​snapshot.checkpoint_id

​snapshot.checkpoint_manifest_digest

​snapshot.parent

​snapshot.created_at

​snapshot.labels

​snapshot.source_sandbox

​Snapshot.create()

​Snapshot.open()

​Snapshot.get()

​Snapshot.list()

​Snapshot.list_dir()

​Snapshot.remove()

​Snapshot.reindex()

​Snapshot.save()

​Snapshot.load()

​snap.verify()

​SnapshotHandle

​handle.digest

​handle.name

​handle.parent_digest

​handle.image_ref

​handle.state_kind

​handle.format

​handle.scope

​handle.fstype

​handle.checkpoint_manifest_digest

​handle.size_bytes

​handle.locality

​handle.availability

​handle.migration_state

​handle.migration_error_code

​handle.created_at

​handle.path

​handle.open()

​handle.remove()

​Types

​SnapshotStateKind

​SnapshotFormat

​SnapshotScope

SandboxHandle

handle.snapshot()

Sandbox

Sandbox.create()

Snapshot

snapshot.path

snapshot.digest

snapshot.size_bytes

snapshot.image_ref

snapshot.image_manifest_digest

snapshot.state_kind

snapshot.format

snapshot.scope

snapshot.fstype

snapshot.checkpoint_id

snapshot.checkpoint_manifest_digest

snapshot.parent

snapshot.created_at

snapshot.labels

snapshot.source_sandbox

Snapshot.create()

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.list_dir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Snapshot.load()

snap.verify()

SnapshotHandle

handle.digest

handle.name

handle.parent_digest

handle.image_ref

handle.state_kind

handle.format

handle.scope

handle.fstype

handle.checkpoint_manifest_digest

handle.size_bytes

handle.locality

handle.availability

handle.migration_state

handle.migration_error_code

handle.created_at

handle.path

handle.open()

handle.remove()

Types

SnapshotStateKind

SnapshotFormat

SnapshotScope