Snapshots

Capture the disk state of a stopped sandbox through the active backend, then boot fresh sandboxes from it. Local snapshots are reusable artifacts; cloud snapshots use managed storage or the organization’s host volume. Snapshots are disk-only and require a sandbox that is not running.

list_dir, reindex, save/save_to, load, and verify keep the same API on every backend, but currently raise UnsupportedError in cloud.

Take a snapshot

handle.snapshot()

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

Snapshot this sandbox under a bare name. Local uses its default snapshot directory; cloud uses managed storage. The sandbox must be stopped or crashed.

Parameters

namestr

Snapshot name. Local stores it in the default snapshot directory; cloud creates a managed snapshot.

Returns

Snapshot

The captured snapshot.

Example

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

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. With no dest_dir, local uses its default snapshot directory and cloud uses managed storage. A dest_dir selects a local parent or cloud host-volume directory.

Parameters

namestr

Snapshot name. Its storage location is selected by the active backend.

from_sandboxstr

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

dest_dirstr | os.PathLike[str] | None

Local parent or cloud host-volume directory. Omit for backend-managed storage.

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

Boot from a snapshot

Sandbox.create()

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

Boot a fresh sandbox from a snapshot by passing from_snapshot= as a peer of image=. The two are mutually exclusive. Passing a Snapshot or SnapshotHandle preserves its backend-relative reference automatically.

Parameters

namestr

Sandbox name, up to 128 UTF-8 bytes.

from_snapshotstr | os.PathLike | Snapshot | SnapshotHandle | None

Backend-relative string, path, or snapshot object 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")

Manage artifacts

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 snapshot through the active backend. Locally, bare names resolve under the default snapshot directory and other values are artifact paths. In cloud, bare values identify managed snapshots and path-like values identify host-volume artifacts. Cheap metadata validation only; use verify() for content checks where supported.

Parameters

path_or_namestr

Backend-relative snapshot name, ID, or 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 lightweight snapshot handle through the active backend.

Parameters

name_or_digeststr

Public identifier understood by the active backend, such as a local name/digest or cloud snapshot ID.

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("after-pip-install", 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

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

Example

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

Bundle a local 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. Cloud raises UnsupportedError.

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 local snapshots directory. Structural and archive-entry checks run during import; recorded payload integrity is preserved for explicit verify(). Compression is detected from magic bytes. Cloud raises UnsupportedError.

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

Inspect

snap.save_to()

async def save_to(
    self,
    out: str | os.PathLike,
    *,
    with_parents: bool = False,
    with_image: bool = False,
    plain_tar: bool = False,
) -> 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.

await snap.save_to("/tmp/after-pip-install.tar.zst", with_image=True)

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. The cloud backend currently raises UnsupportedError.

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:..."},
}

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.

handle.save_to()

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

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

Types

Snapshot

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
`reference`	`str`	Stable backend-relative restore reference
`reference_kind`	`Literal["id", "path"]`	How the selected backend resolves the reference
`digest`	`str`	Canonical content digest (`sha256:hex`). The snapshot’s identity
`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
`verify()`	`Awaitable[dict[str, Any]]`	Recompute and check the upper-layer integrity hash. See `verify()`

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
`digest`	`str`	Manifest digest, canonical identity
`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.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

Getting Started

SDKs

CLI

Take a snapshot

handle.snapshot()

Snapshot.create()

Boot from a snapshot

Sandbox.create()

Manage artifacts

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.list_dir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Move artifacts

Snapshot.load()

Inspect

snap.save_to()

snap.verify()

handle.open()

handle.remove()

handle.save_to()

Types

Snapshot

SnapshotHandle

SnapshotStateKind

SnapshotFormat

SnapshotScope

​Take a snapshot

​handle.snapshot()

​Snapshot.create()

​Boot from a snapshot

​Sandbox.create()

​Manage artifacts

​Snapshot.open()

​Snapshot.get()

​Snapshot.list()

​Snapshot.list_dir()

​Snapshot.remove()

​Snapshot.reindex()

​Snapshot.save()

​Move artifacts

​Snapshot.load()

​Inspect

​snap.save_to()

​snap.verify()

​handle.open()

​handle.remove()

​handle.save_to()

​Types

​Snapshot

​SnapshotHandle

​SnapshotStateKind

​SnapshotFormat

​SnapshotScope

Take a snapshot

handle.snapshot()

Snapshot.create()

Boot from a snapshot

Sandbox.create()

Manage artifacts

Snapshot.open()

Snapshot.get()

Snapshot.list()

Snapshot.list_dir()

Snapshot.remove()

Snapshot.reindex()

Snapshot.save()

Move artifacts

Snapshot.load()

Inspect

snap.save_to()

snap.verify()

handle.open()

handle.remove()

handle.save_to()

Types

Snapshot

SnapshotHandle

SnapshotStateKind

SnapshotFormat

SnapshotScope