docs/sdk/python/snapshots.mdx
Create and manage disk-only snapshots of stopped sandboxes. See Snapshots for usage and lifecycle concepts.
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().
handle = await Sandbox.get("baseline")
snap = await handle.snapshot("after-pip-install")
print(snap.digest)
@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.
# 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")
A fully-parsed snapshot artifact. Properties are read-only attributes (not async).
str
Path to the artifact directory
str
Canonical content digest (sha256:hex). The snapshot's identity
int \| None
Apparent size of the captured upper layer in bytes (sparse on disk), when recorded
str
Image reference the snapshot was taken from
str
OCI manifest digest of the pinned image
File-backed or checkpoint-backed state
SnapshotFormat \| None
On-disk format for file-backed state
Captured state scope
str \| None
Filesystem type for file-backed state (e.g. "ext4")
str \| None
Checkpoint identifier for checkpoint-backed state
str \| None
Checkpoint manifest digest for checkpoint-backed state
str \| None
Parent snapshot's digest, or None for a root
str
RFC 3339 timestamp
dict[str, str]
User-supplied labels
str \| None
Best-effort source-sandbox name
@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.
snap = await Snapshot.create(
"after-pip-install",
from_sandbox="baseline",
labels={"stage": "post-deps"},
record_integrity=True,
)
@staticmethod
async def open(path_or_name: str) -> Snapshot
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.
@staticmethod
async def get(name_or_digest: str) -> SnapshotHandle
h = await Snapshot.get("after-pip-install")
print(h.digest)
Look up a handle in the local index by name, digest, or path.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>name_or_digest</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Snapshot name, digest, or path.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshothandle">SnapshotHandle</a></div> <div className="msb-param-desc">Lightweight handle backed by an index row.</div> </div> </div>@staticmethod
async def list() -> list[SnapshotHandle]
for h in await Snapshot.list():
print(h.name, h.digest)
List indexed snapshots from the local DB cache.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshothandle">list[SnapshotHandle]</a></div> <div className="msb-param-desc">Indexed snapshot handles.</div> </div> </div>@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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>dir</code><span className="msb-type">str | os.PathLike</span></div> <div className="msb-param-desc">Directory to scan for artifacts.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#snapshot">list[Snapshot]</a></div> <div className="msb-param-desc">One snapshot per valid artifact directory.</div> </div> </div>@staticmethod
async def remove(path_or_name: str, *, force: bool = False) -> None
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.
@staticmethod
async def reindex(dir: str | os.PathLike | None = None) -> int
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.
count = await Snapshot.reindex()
print(f"indexed {count} snapshots")
@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
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.
await Snapshot.save(
"after-pip-install",
"/tmp/after-pip-install.tar.zst",
with_parents=True,
)
@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.
h = await Snapshot.load("/tmp/after-pip-install.tar.zst")
print(h.path)
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")
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 report shape:
{
"digest": "sha256:...",
"path": "/path/to/artifact",
"upper": {"kind": "not_recorded"} # no integrity recorded
| {"kind": "verified", "algorithm": "...", "digest": "sha256:..."},
}
Lightweight handle backed by an index row. Properties are read-only attributes (not async).
str
Manifest digest, canonical identity
str \| None
Convenience alias
str \| None
Parent snapshot digest, or None for a root
str
Image the snapshot was taken from
File-backed or checkpoint-backed state
SnapshotFormat \| None
On-disk format for file-backed state
Captured state scope
str \| None
Filesystem type for file-backed state
str \| None
Checkpoint manifest digest for checkpoint-backed state
int \| None
Apparent upper size at index time
str
Artifact locality reported by the index
str
Artifact availability reported by the index
str
Current migration state
str \| None
Migration error code, when migration failed
float
ms since Unix epoch
str
Local artifact directory path
async def open(self) -> Snapshot
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.
async def remove(self, *, force: bool = False) -> None
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.
Snapshot state representation.
| Member | Value | Description |
|---|---|---|
SnapshotStateKind.FILE | "file" | File-backed upper-layer state |
SnapshotStateKind.CHECKPOINT | "checkpoint" | Checkpoint-manifest-backed state |
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 |
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