Snapshots

Rust SDK - Snapshot API reference

Capture a stopped sandbox’s writable upper layer, then list it or boot a fresh sandbox from it through the active backend. Local snapshots are self-describing, content-addressed artifacts on disk; cloud snapshots use managed storage or the organization’s host volume. See Snapshots for concepts and walkthroughs; this page is the Rust SDK reference.

Snapshots are disk-only today and capture a sandbox that is stopped or crashed. list_dir, reindex, save/save_to, load, and verify remain on the shared Snapshot API, but currently return MicrosandboxError::Unsupported with the cloud backend.

Static methods

Snapshot::builder()

fn builder(name: impl Into<String>) -> SnapshotBuilder

Start configuring a new snapshot named name. Locally, the default destination is ~/.microsandbox/snapshots/<name>/; in cloud, the default is managed object storage. dest_dir() selects a local parent directory or a path on the organization’s host volume. The source sandbox is set with from_sandbox(), which is required.

Parameters

nameimpl Into<String>

Bare snapshot name. Must not be empty, contain /, or start with ..

Returns

SnapshotBuilder

Builder for configuring the snapshot.

Example

let snap = Snapshot::builder("baseline")
    .from_sandbox("api")
    .create()
    .await?;

---

Snapshot::create()

async fn create(config: SnapshotConfig) -> MicrosandboxResult<Snapshot>

Create a snapshot from a stopped sandbox through the active backend. Locally, this atomically writes the artifact and updates the rebuildable local index. In cloud, it starts a snapshot operation and waits for the managed or host-volume snapshot to become available. Most callers use the builder’s create().

Parameters

configSnapshotConfig

Name, source sandbox, labels, and integrity flag.

Returns

Snapshot

The created artifact handle.

Example

let snap = Snapshot::create(
    Snapshot::builder("baseline").from_sandbox("api").build()?
).await?;

---

Snapshot::open()

async fn open(path_or_name: impl AsRef<str>) -> MicrosandboxResult<Snapshot>

Example

let snap = Snapshot::open("baseline").await?;
println!("{}", snap.manifest().image.reference);

Open an existing snapshot by a backend-relative string. 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. Prefer open_ref() when a typed SnapshotReference is already available.

Parameters

path_or_nameimpl AsRef<str>

Bare snapshot name or filesystem path to an artifact directory.

Returns

Snapshot

The opened artifact handle.

Snapshot::open_ref()

async fn open_ref(reference: impl Into<SnapshotReference>) -> MicrosandboxResult<Snapshot>

Open a snapshot from an explicit SnapshotReference. Use this when passing through a reference returned by another SDK operation; it preserves whether the backend should resolve the value as an identifier or a path.

let snap = Snapshot::open_ref(SnapshotReference::Id(snapshot_id)).await?;

Snapshot::get()

async fn get(name_or_digest: &str) -> MicrosandboxResult<SnapshotHandle>

Example

let h = Snapshot::get("after-pip-install").await?;
println!("{} from {}", h.digest(), h.image_ref());

Look up a lightweight SnapshotHandle using the active backend: the local index locally, or the managed snapshot API in cloud.

Parameters

name_or_digest&str

Public identifier understood by the active backend (for example a local name/digest or cloud snapshot ID).

Returns

SnapshotHandle

Handle backed by the matching index row.

Snapshot::list()

async fn list() -> MicrosandboxResult<Vec<SnapshotHandle>>

Example

for h in Snapshot::list().await? {
    println!("{:?} - {}", h.name(), h.digest());
}

List snapshots from the active backend. Locally this uses the local index; in cloud it paginates through managed snapshots. Host-volume artifacts are not included automatically.

Returns

Vec<SnapshotHandle>

Indexed snapshot handles, ordered by creation time descending.

Snapshot::list_dir()

async fn list_dir(dir: impl AsRef<Path>) -> MicrosandboxResult<Vec<Snapshot>>

Walk a directory and parse each subdirectory’s manifest. Does not touch the index. Skips entries that don’t look like snapshot artifacts (no snapshot.json) and malformed artifacts.

Parameters

dirimpl AsRef<Path>

Directory to scan for artifacts.

Returns

Vec<Snapshot>

One handle per valid artifact found.

Snapshot::remove()

async fn remove(path_or_name: &str, force: bool) -> MicrosandboxResult<()>

Example

Snapshot::remove("after-pip-install", false).await?;

Remove a snapshot artifact (by digest, name, or path) and its index row. Refuses if the snapshot has indexed children unless force is set. The artifact directory is deleted on success and the parent’s child count is decremented.

Parameters

path_or_name&str

Snapshot digest, name, or artifact path.

forcebool

When true, remove even if the snapshot has indexed children.

Snapshot::remove_ref()

async fn remove_ref(
    reference: impl Into<SnapshotReference>,
    force: bool,
) -> MicrosandboxResult<()>

Remove a snapshot using an explicit backend-neutral reference. Prefer this over remove() when the value came from Snapshot::reference() or SnapshotHandle::reference().

Snapshot::reindex()

async fn reindex(dir: impl AsRef<Path>) -> MicrosandboxResult<usize>

Rebuild the local index from the artifacts in dir. Upserts an index row for every artifact found, then recomputes parent-edge child counts in one pass so the cache stays honest about the current set of artifacts.

Parameters

dirimpl AsRef<Path>

Directory of artifacts to index.

Returns

usize

Number of artifacts indexed.

Example

let n = Snapshot::reindex("/data/snapshots").await?;
println!("indexed {n} snapshots");

Snapshot::reindex_default()

async fn reindex_default() -> MicrosandboxResult<usize>

Rebuild the local snapshot index from the configured default snapshot directory. This is equivalent to reindex() with the local backend’s configured store and returns MicrosandboxError::Unsupported on backends without a rebuildable artifact index.

---

Snapshot::save()

staticasync

async fn save(name_or_path: &str, out: &Path, opts: SaveOpts) -> MicrosandboxResult<()>

Bundle a snapshot into a .tar.zst archive (or plain .tar) at out. Recorded payload integrity is preserved but not executed implicitly; call verify() when an independent content scan is part of your workflow. See SaveOpts to also include ancestors and the OCI image cache.

Parameters

name_or_path&str

Snapshot name or artifact path to save.

out&Path

Output archive path. Parent directories are created if missing.

optsSaveOpts

Bundling options. SaveOpts::default() writes the head snapshot only, zstd-compressed.

Example

use microsandbox::snapshot::SaveOpts;
use std::path::Path;

Snapshot::save(
    "baseline",
    Path::new("/tmp/baseline.tar.zst"),
    SaveOpts { with_parents: true, with_image: true, ..Default::default() },
).await?;

---

Snapshot::load()

staticasync

async fn load(archive_path: &Path, dest: Option<&Path>) -> MicrosandboxResult<SnapshotHandle>

Example

use std::path::Path;

let h = Snapshot::load(Path::new("/tmp/baseline.tar.zst"), None).await?;
println!("loaded {}", h.digest());

Unpack a snapshot archive (.tar.zst or .tar, detected from magic bytes) into the snapshots directory (or dest), routing any bundled image-cache entries into the global cache and registering everything found in the index. Structural and archive-entry checks remain mandatory, while recorded payload integrity is preserved for explicit verify(). Returns a handle for the head snapshot.

Parameters

archive_path&Path

Archive to unpack.

destOption<&Path>

Destination directory. None uses the default snapshots directory.

Returns

SnapshotHandle

Handle for the head (last-listed) snapshot.

Example

use std::path::Path;

let h = Snapshot::load(Path::new("/tmp/baseline.tar.zst"), None).await?;
println!("loaded {}", h.digest());

---

Instance methods

Methods on an opened Snapshot artifact.

snap.digest()

fn digest(&self) -> &str

Canonical content digest of this snapshot’s manifest (sha256:hex). This is the snapshot’s identity.

Returns

&str

Manifest digest in sha256:hex form.

snap.reference()

fn reference(&self) -> SnapshotReference

Return the stable, backend-neutral reference accepted by SandboxBuilder::from_snapshot_ref(), Snapshot::open_ref(), and Snapshot::remove_ref(). It contains either an identifier or a path in the selected backend’s namespace; callers can pass it through without inspecting which storage implementation produced it.

snap.manifest()

fn manifest(&self) -> &Manifest

Example

let snap = Snapshot::open("baseline").await?;
let m = snap.manifest();
println!("{} @ {}", m.image.reference, m.image.manifest_digest);

The parsed Manifest: schema, format, fstype, image reference, parent, creation time, labels, and upper-layer metadata.

Returns

&Manifest

Parsed snapshot manifest.

snap.size_bytes()

fn size_bytes(&self) -> Option<u64>

Backend-reported stored payload size. This is the apparent upper-file size for local and host-volume artifacts, and the stored archive size for managed cloud snapshots.

Returns

u64

Upper-layer apparent size in bytes.

snap.path()

fn path(&self) -> MicrosandboxResult<&Path>

Return the local artifact directory. Cloud snapshots return MicrosandboxError::Unsupported because managed and host-volume artifacts are not paths on the client host. Use reference() for backend-neutral restore and lifecycle operations.

snap.save_to()

async fn save_to(&self, out: &Path, opts: SaveOpts) -> MicrosandboxResult<()>

Bundle this snapshot into an archive using the backend retained when it was created or opened. This avoids re-resolving its reference through the current default backend. Artifact archives are currently local-only; other backends return MicrosandboxError::Unsupported.

snap.verify()

async fn verify(&self) -> MicrosandboxResult<SnapshotVerifyReport>

Example

use microsandbox::snapshot::UpperVerifyStatus;

let snap = Snapshot::open("baseline").await?;
match snap.verify().await?.upper {
    UpperVerifyStatus::Verified { algorithm, .. } => println!("ok via {algorithm}"),
    UpperVerifyStatus::NotRecorded => println!("no integrity hash recorded"),
}

Recompute the upper layer’s recorded content integrity and compare it against the descriptor. Current BLAKE3 Merkle integrity skips known all-hole subtrees and hashes allocated leaves in batches. Released SHA algorithms retain their exact verifier and may still cost O(logical size). Returns NotRecorded without reading payload contents when the descriptor has integrity: null; errors with SnapshotIntegrity on mismatch. The cloud backend currently returns MicrosandboxError::Unsupported.

Returns

SnapshotVerifyReport

Digest, path, and upper-layer verification status.

SnapshotHandle methods

Accessors and lifecycle on a SnapshotHandle returned by the active backend. Returned by Snapshot::get(), Snapshot::list(), and Snapshot::load().

h.digest()

fn digest(&self) -> &str

Manifest digest (sha256:hex), the canonical identity.

h.name()

fn name(&self) -> Option<&str>

Name alias, or None for digest-only entries.

h.parent_digest()

fn parent_digest(&self) -> Option<&str>

The parent snapshot’s digest, or None for a root. Always None today; populated once chained snapshots land.

---

h.scope()

instance

fn scope(&self) -> SnapshotScope

Snapshot payload scope: SnapshotScope::Disk for a disk-only snapshot, Resumable once resumable snapshots land. Always Disk today.

---

h.image_ref()

fn image_ref(&self) -> &str

Image reference the snapshot was taken from.

h.format()

fn format(&self) -> SnapshotFormat

On-disk format of the upper layer.

Returns

SnapshotFormat

Upper-layer format (Raw today).

h.size_bytes()

fn size_bytes(&self) -> Option<u64>

Backend-reported stored payload size, if known.

h.path()

fn path(&self) -> MicrosandboxResult<&Path>

Return the local artifact directory. Cloud snapshots return MicrosandboxError::Unsupported. Use reference() for backend-neutral restore and lifecycle operations.

h.created_at()

fn created_at(&self) -> chrono::NaiveDateTime

Snapshot creation time, parsed from the manifest.

h.open()

async fn open(&self) -> MicrosandboxResult<Snapshot>

Example

let h = Snapshot::get("baseline").await?;
let snap = h.open().await?;
snap.verify().await?;

Open the underlying snapshot metadata using the backend retained by the handle, without requiring the caller to interpret its storage location.

Returns

Snapshot

The opened artifact.

h.remove()

async fn remove(&self, force: bool) -> MicrosandboxResult<()>

Example

let h = Snapshot::get("baseline").await?;
h.remove(false).await?;

Remove this snapshot through the backend retained by the handle, preserving its identifier-versus-path reference kind.

Parameters

forcebool

When true, remove even if the snapshot has indexed children.

h.save_to()

async fn save_to(&self, out: &Path, opts: SaveOpts) -> MicrosandboxResult<()>

Bundle the referenced snapshot into an archive through the backend retained by this handle. Artifact archives are currently local-only; other backends return MicrosandboxError::Unsupported.

Sandbox entry points

Snapshot-related methods that live on the sandbox builder and handle. See Sandbox for the full sandbox API.

.from_snapshot()

fn from_snapshot(self, path_or_name: impl Into<String>) -> Self

Example

let sb = Sandbox::builder("api-restored")
    .from_snapshot("after-pip-install")
    .create()
    .await?;

SandboxBuilder setter. Boot a fresh sandbox from a snapshot artifact. The snapshot already pins the image reference and digest, so this is mutually exclusive with image() and image_with(). The artifact is structurally opened at create() time; persistent payload integrity is checked only through explicit Snapshot::verify().

Parameters

path_or_nameimpl Into<String>

Backend-relative snapshot name, ID, or path.

.from_snapshot_ref()

fn from_snapshot_ref(self, reference: impl Into<SnapshotReference>) -> Self

Boot from an explicit backend-neutral snapshot reference. This is the safest way to pass a Snapshot or SnapshotHandle reference into a new sandbox without reinterpreting an identifier as a path.

let restored = Sandbox::builder("api-restored")
    .from_snapshot_ref(snapshot.reference())
    .create()
    .await?;

h.snapshot()

async fn snapshot(&self, name: &str) -> MicrosandboxResult<Snapshot>

SandboxHandle method. Snapshot this sandbox under a bare name using the handle’s backend. Local uses its default snapshot directory; cloud uses managed storage. The sandbox must be stopped or crashed; running sandboxes are rejected with SnapshotSandboxRunning.

Parameters

name&str

Bare snapshot name.

Returns

Snapshot

The created artifact handle.

h.snapshot_to()

async fn snapshot_to(&self, path: impl AsRef<Path>) -> MicrosandboxResult<Snapshot>

Example

let h = Sandbox::get("api").await?;
h.stop().await?;
let snap = h.snapshot_to("/data/snapshots/baseline").await?;

---

SnapshotBuilder

Builder for a SnapshotConfig. Obtained via Snapshot::builder(name). A source sandbox is required (from_sandbox); the other setters are optional. Every setter returns Self, so calls chain.

let snap = Snapshot::builder("after-pip-install")
    .from_sandbox("api")           // sandbox to capture
    .label("stage", "post-deps")
    .force()                       // overwrite if it exists
    .record_integrity()            // hash the upper layer
    .create()
    .await?;

---

.from_sandbox()

builder

fn from_sandbox(self, source_sandbox: impl Into<String>) -> Self

Set the sandbox to capture. Required; build() and create() fail without it.

Parameters

source_sandboximpl Into<String>

Name of the source sandbox. Must be stopped or crashed, and rooted on an OCI image.

---

.dest_dir()

builder

fn dest_dir(self, dest_dir: impl Into<PathBuf>) -> Self

Create the artifact under this parent directory instead of the default snapshots store. The artifact directory is dest_dir/<name>; the name stays the snapshot’s identity either way.

Parameters

dest_dirimpl Into<PathBuf>

Parent directory to create the artifact in (e.g. a larger volume).

.label()

fn label(self, key: impl Into<String>, value: impl Into<String>) -> Self

Add a user label. Can be called multiple times. Labels are sorted by key in the manifest’s canonical form.

Parameters

keyimpl Into<String>

Label key.

valueimpl Into<String>

Label value.

.force()

fn force(self) -> Self

Overwrite an existing artifact with the same name. Without this, creation fails with SnapshotAlreadyExists if the artifact directory exists.

.record_integrity()

fn record_integrity(self) -> Self

Compute and record sparse-aware BLAKE3 Merkle integrity during creation. verify() checks it explicitly; ordinary open, boot, save, load, and upgrade preserve the value without adding an independent payload pass.

---

.resumable()

builder

fn resumable(self) -> Self

Request a future resumable snapshot (disk plus VM state). create() currently fails with Unsupported; resumable capture has not landed yet.

.build()

fn build(self) -> MicrosandboxResult<SnapshotConfig>

Materialize the SnapshotConfig without creating the snapshot. Errors with InvalidConfig if from_sandbox was not called. For capturing, use create instead; it calls build internally.

Returns

SnapshotConfig

Validated snapshot configuration.

.create()

async fn create(self) -> MicrosandboxResult<Snapshot>

Build and execute the snapshot in one step. Equivalent to Snapshot::create(self.build()?).

Returns

Snapshot

The created artifact handle.

Types

SnapshotReference

enum

A backend-neutral snapshot locator. Obtain one from Snapshot::reference() or SnapshotHandle::reference() and pass it to SandboxBuilder::from_snapshot_ref(), Snapshot::open_ref(), or Snapshot::remove_ref(). This preserves whether a value is an identifier or a path without exposing the selected backend.

Variant	Meaning
Auto(String)	Compatibility string interpreted automatically by the active backend
Id(String)	Identifier resolved by the selected backend
Path(String)	Path in the selected backend’s filesystem namespace

Use SnapshotReference::auto(), id(), or path() to construct a reference. value() returns the underlying string and kind() returns auto, id, or path.

SnapshotHandle

struct

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

A lightweight handle returned by the active backend. Use open() to read the snapshot metadata. The handle retains its backend, so open() and remove() work without the caller interpreting its storage location.

Method	Type	Description
digest()	&str	Manifest digest (sha256:hex)
name()	Option<&str>	Name alias; None for digest-only entries
parent_digest()	Option<&str>	Parent snapshot digest, or None for a root
scope()	SnapshotScope	Snapshot payload scope (Disk today)
image_ref()	&str	Source image reference
format()	SnapshotFormat	On-disk upper format
size_bytes()	Option<u64>	Upper file size at index time
created_at()	chrono::NaiveDateTime	Creation time from the manifest
reference()	SnapshotReference	Stable backend-neutral restore reference
open()	Result<Snapshot>	Open the underlying artifact
remove(force)	Result<()>	Remove this snapshot
save_to(out, opts)	Result<()>	Bundle through the backend retained by this handle

SnapshotConfig

Used by Snapshot::create() · returned by build()

Inputs to create a snapshot. A type alias for SnapshotSpec. Usually built via SnapshotBuilder rather than constructed directly.

Field	Type	Description
name	String	Snapshot name; storage location is selected by the active backend
dest_dir	Option<PathBuf>	Local parent or cloud host-volume directory; None uses backend-managed storage
source_sandbox	String	Name of the source sandbox; must be stopped
labels	Vec<(String, String)>	User-supplied labels
force	bool	Overwrite an existing artifact with the same name
record_integrity	bool	Compute and record upper-layer integrity at creation
resumable	bool	Request a resumable snapshot; returns an unsupported-feature error today

SnapshotFormat

Used by format() · Manifest.format

On-disk format of the captured upper layer. Today only Raw is produced; the variant exists so qcow2 chains drop in later without a schema migration.

Value	Description
Raw	Raw ext4 image, sparse on disk
Qcow2	qcow2 with optional backing chain (future)

SnapshotScope

enum

Used by scope() · Manifest.scope

Snapshot payload scope. Parsing accepts every known scope so older runtimes can still list and inspect artifacts they cannot restore; create and restore paths enforce support. Re-exported as microsandbox::snapshot::SnapshotScope.

Value	Description
Disk	Disk-only snapshot; captures the writable filesystem state
Resumable	Reserved for future memory/device-state capture

SaveOpts

struct

Used by Snapshot::save() and instance save_to() methods

Options for Snapshot::save() and instance save_to() methods. Implements Default; SaveOpts::default() writes the head snapshot only, zstd-compressed.

Field	Type	Description
with_parents	bool	Walk the parent chain and include each ancestor in the archive
with_image	bool	Bundle the OCI image artifacts (EROFS layers, fsmeta, VMDK descriptor) from the global cache so the archive boots offline
plain_tar	bool	Skip zstd compression and write a plain .tar. Default: zstd

SnapshotVerifyReport

Returned by verify()

Result of explicit snapshot verification.

Field	Type	Description
digest	String	Snapshot manifest digest
path	PathBuf	Artifact directory
upper	UpperVerifyStatus	Upper-layer content verification result

UpperVerifyStatus

Used by SnapshotVerifyReport.upper

Upper-layer content verification result.

Variant	Fields	Description
NotRecorded	-	No content integrity descriptor was recorded in the manifest
Verified	- algorithm: String - digest: String	Recorded integrity matched the computed digest

Manifest

Returned by manifest()

The snapshot artifact manifest, the source of truth for an artifact, serialized as the snapshot.json descriptor (DESCRIPTOR_FILENAME). Re-exported as microsandbox::snapshot::Manifest. Its SHA-256 digest over the canonical byte form is the snapshot’s identity. Field order is load-bearing (it determines the canonical byte layout) and must not be reordered.

Field	Type	Description
schema	u32	Manifest schema version; readers reject unknown values
artifact	String	Artifact kind; always "snapshot"
scope	SnapshotScope	Payload scope; only disk snapshots are created today
format	SnapshotFormat	On-disk format of the upper layer
fstype	String	Filesystem type inside the upper (e.g. ext4)
image	ImageRef	Image the snapshot was taken from
parent	Option<String>	Parent snapshot digest, or None for a root
created_at	String	RFC 3339 creation timestamp
labels	BTreeMap<String, String>	User-supplied labels, sorted by key in canonical form
upper	UpperLayer	The captured upper layer
source_sandbox	Option<String>	Best-effort name of the source sandbox (informational)

ImageRef

Used by Manifest.image

Reference to the OCI image the snapshot was taken from. Re-exported as microsandbox::snapshot::ImageRef.

Field	Type	Description
reference	String	Human-readable image reference (e.g. docker.io/library/python:3.12)
manifest_digest	String	Digest of the OCI manifest, in sha256:hex form

UpperLayer

Used by Manifest.upper

Captured upper-layer file metadata. Re-exported as microsandbox::snapshot::UpperLayer.

Field	Type	Description
file	String	Filename inside the artifact directory (e.g. upper.ext4)
size_bytes	u64	Apparent size in bytes (ext4 virtual size; sparse on disk)
integrity	Option<UpperIntegrity>	Optional content integrity descriptor; None on local hot paths

UpperIntegrity

Used by UpperLayer.integrity

Content integrity descriptor for the captured upper layer.

Field	Type	Description
Variant	Serialized algorithm	Fields	Purpose
---------	----------------------	--------	---------
Sha256	sha256	digest	Exact released compatibility
SparseSha256V1	msb-sparse-sha256-v1	digest	Exact released sparse-SHA compatibility
FileMerkleBlake3V1	msb-file-merkle-blake3-v1	root, logical_size, leaf_size	Current opt-in sparse-aware integrity