Documentation Index
Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
Use this file to discover all available pages before exploring further.
Disk-only snapshots of a stopped sandbox. See Snapshots for concepts and walkthroughs; this page is the Python SDK reference.
from microsandbox import Sandbox, Snapshot, SnapshotHandle
Snapshots are disk-only and stopped-only. Live snapshots and qcow2 backing chains are tracked as future work.
Sandbox.create() — snapshot= kwarg
@staticmethod
async def create(name_or_config, *, snapshot: str | os.PathLike | None = None, **kwargs) -> Sandbox
snapshot= as a peer of image=. The two are mutually exclusive — pass exactly one.
# Boot from a snapshot
sb = await Sandbox.create("worker", snapshot="after-pip-install")
# Or from an image (existing flow, unchanged)
sb = await Sandbox.create("worker", image="python:3.12")
ValueError — both image= and snapshot= were passed or neither, the snapshot artifact doesn’t exist, or the artifact’s manifest failed validation
SandboxHandle methods
snapshot()
async def snapshot(self, name: str) -> Snapshot
~/.microsandbox/snapshots/<name>/). For an explicit filesystem destination, see snapshot_to().
Errors
SnapshotSandboxRunning — the sandbox is not stoppedSnapshotAlreadyExists — destination exists (use Snapshot.create(..., force=True) to overwrite)
snapshot_to()
async def snapshot_to(self, path: str | os.PathLike) -> Snapshot
Snapshot (instance)
Properties are read-only attributes (not async).
| Property | Type | Description |
|---|
path | str | Path to the artifact directory |
digest | str | Canonical content digest (sha256:hex). The snapshot’s identity. |
size_bytes | int | Apparent size of the captured upper layer in bytes (sparse on disk) |
image_ref | str | Image reference the snapshot was taken from |
image_manifest_digest | str | OCI manifest digest of the pinned image |
format | str | "raw" or "qcow2" (always "raw" today) |
fstype | str | Filesystem type inside the upper (e.g. "ext4") |
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 |
verify()
async def verify(self) -> dict[str, Any]
report = await snap.verify()
if report["upper"]["kind"] == "verified":
print(f"hash matches: {report['upper']['digest']}")
else:
print("no integrity hash recorded")
{
"digest": "sha256:...",
"path": "/path/to/artifact",
"upper": {"kind": "not_recorded"} # no integrity recorded
| {"kind": "verified", "algorithm": "...", "digest": "sha256:..."},
}
Snapshot (static)
Snapshot.create()
@staticmethod
async def create(
source_sandbox: str,
*,
name: str | None = None,
path: str | os.PathLike | None = None,
labels: dict[str, str] | None = None,
force: bool = False,
record_integrity: bool = False,
) -> Snapshot
name= (resolved under the default snapshots directory) or path= (explicit filesystem destination) is required.
snap = await Snapshot.create(
"baseline",
name="after-pip-install",
labels={"stage": "post-deps"},
record_integrity=True,
)
Snapshot.open()
@staticmethod
async def open(path_or_name: str) -> Snapshot
verify() for content checks.
Snapshot.get()
@staticmethod
async def get(name_or_digest: str) -> SnapshotHandle
Snapshot.list()
@staticmethod
async def list() -> list[SnapshotHandle]
Snapshot.list_dir()
@staticmethod
async def list_dir(dir: str | os.PathLike) -> list[Snapshot]
Snapshot.remove()
@staticmethod
async def remove(path_or_name: str, *, force: bool = False) -> None
force=True.
Snapshot.reindex()
@staticmethod
async def reindex(dir: str | os.PathLike | None = None) -> int
dir (default: configured snapshots dir) and rebuild the local index. Returns the number of artifacts indexed.
Snapshot.export()
@staticmethod
async def export(
name_or_path: str,
out: str | os.PathLike,
*,
with_parents: bool = False,
with_image: bool = False,
plain_tar: bool = False,
) -> None
.tar.zst archive. Computes and embeds the integrity hash in the bundled manifest if not already present.
Snapshot.import_()
@staticmethod
async def import_(
archive: str | os.PathLike,
*,
dest: str | os.PathLike | None = None,
) -> SnapshotHandle
.tar.zst or .tar) into the snapshots directory, verifying recorded integrity on the way in. Compression is detected from magic bytes.
The trailing underscore is intentional — import is a reserved Python keyword.
SnapshotHandle
Lightweight handle backed by an index row. Returned by Snapshot.list() and Snapshot.get().
| Property | Type | Description |
|---|
digest | str | Manifest digest — canonical identity |
name | str | None | Convenience alias |
parent_digest | str | None | Parent snapshot digest (None today; populated when chains land) |
image_ref | str | Image the snapshot was taken from |
format | str | "raw" or "qcow2" |
size_bytes | int | None | Apparent upper size at index time |
created_at | float | ms since Unix epoch |
path | str | Local artifact directory path |
h = await Snapshot.get("after-pip-install")
snap = await h.open() # metadata-validated
await h.remove(force=False) # refuse if has children
