--- title: Snapshots description: Rust SDK - Snapshot API reference --- Capture a stopped sandbox's writable upper layer into a self-describing, content-addressed artifact on disk, then list, verify, export, import, or boot a fresh sandbox from it. See [Snapshots](/sandboxes/snapshots) for concepts and walkthroughs; this page is the Rust SDK reference.

Static · Snapshot10

Snapshot::builder()configure a new snapshot Snapshot::create()create from a config Snapshot::open()open an artifact Snapshot::get()handle from the index Snapshot::list()indexed snapshots Snapshot::list_dir()artifacts in a directory Snapshot::remove()delete an artifact Snapshot::reindex()rebuild the index Snapshot::export()bundle to an archive Snapshot::import()unpack an archive

Instance · Snapshot5

snap.digest()content identity snap.path()artifact directory snap.manifest()parsed manifest snap.size_bytes()upper-layer size snap.verify()recheck integrity

Instance · SnapshotHandle10

h.digest()manifest digest h.name()name alias h.parent_digest()parent snapshot h.image_ref()source image h.format()upper format h.size_bytes()indexed size h.created_at()creation time h.path()artifact directory h.open()read the artifact h.remove()delete this snapshot

Sandbox entry points3

.from_snapshot()boot from a snapshot h.snapshot()snapshot a stopped sandbox h.snapshot_to()snapshot to a path

Builder · SnapshotBuilder8

.destination() .name() .path() .label() .force() .record_integrity() .build() .create()

Types

SnapshotHandle SnapshotConfig SnapshotDestination SnapshotFormat ExportOpts SnapshotVerifyReport UpperVerifyStatus Manifest ImageRef UpperLayer UpperIntegrity
Snapshots are **local-only** and **disk-only** today: they capture a sandbox that is stopped or crashed, and every operation runs against the default local backend. Cloud snapshots and qcow2 backing chains are deferred.

Typical flow

```rust use microsandbox::{Sandbox, Snapshot}; // 1. stop the sandbox you want to capture let sb = Sandbox::get("api").await?; sb.stop().await?; // 2. capture its writable upper layer let snap = Snapshot::builder("api") .name("after-pip-install") // bare name in the default dir .record_integrity() // hash the upper layer .create() .await?; println!("{} ({} bytes)", snap.digest(), snap.size_bytes()); // 3. boot a fresh sandbox from it let restored = Sandbox::builder("api-restored") .from_snapshot("after-pip-install") .create() .await?; ``` ## Static methods --- #### Snapshot::builder()
static
```rust fn builder(source_sandbox: impl Into) -> SnapshotBuilder ``` Start configuring a new snapshot of `source_sandbox`. The builder lets you set the destination, labels, and whether to record content integrity before capturing. See [`SnapshotBuilder`](#snapshotbuilder) for all options.

Parameters

source_sandboximpl Into<String>
Name of the source sandbox. Must be stopped or crashed, and rooted on an OCI image.

Returns

SnapshotBuilder
Builder for configuring the snapshot.
```rust let snap = Snapshot::builder("api") .name("baseline") .create() .await?; ``` --- #### Snapshot::create()
staticasync
```rust async fn create(config: SnapshotConfig) -> MicrosandboxResult ``` Create a snapshot artifact from a stopped sandbox. Writes `manifest.json` and the captured `upper.ext4` into the destination directory atomically (the manifest is renamed into place last), then best-effort upserts a row into the local index. Index failures are logged but do not fail the call; the artifact is the source of truth. Most callers use the [builder](#snapshotbuilder)'s [`create()`](#create) instead of constructing a [`SnapshotConfig`](#snapshotconfig) by hand.

Parameters

configSnapshotConfig
Source sandbox, destination, labels, and integrity flag.

Returns

Snapshot
The created artifact handle.
```rust let snap = Snapshot::create( Snapshot::builder("api").name("baseline").build()? ).await?; ``` --- #### Snapshot::open()
staticasync
```rust async fn open(path_or_name: impl AsRef) -> MicrosandboxResult ``` Open an existing artifact by path or bare name. Bare names (no path separator, not starting with `.` or `~`) resolve under the default snapshots directory; anything else is treated as a path. This is a fast metadata operation: it verifies the manifest structure, recomputes the manifest digest, and checks that the upper file exists with the recorded size. It does **not** read the full upper contents; use [`verify()`](#snap-verify) for that.

Parameters

path_or_nameimpl AsRef<str>
Bare snapshot name or filesystem path to an artifact directory.

Returns

The opened artifact handle.
```rust let snap = Snapshot::open("baseline").await?; println!("{}", snap.manifest().image.reference); ``` --- #### Snapshot::get()
staticasync
```rust async fn get(name_or_digest: &str) -> MicrosandboxResult ``` Look up a lightweight [`SnapshotHandle`](#snapshothandle) in the local index by name, digest (`sha256:`/`sha512:` prefix), or path.

Parameters

name_or_digest&str
Snapshot name, manifest digest, or artifact path.

Returns

Handle backed by the matching index row.
```rust let h = Snapshot::get("after-pip-install").await?; println!("{} from {}", h.digest(), h.image_ref()); ``` --- #### Snapshot::list()
staticasync
```rust async fn list() -> MicrosandboxResult> ``` List indexed snapshots from the local DB cache, newest first. External-path artifacts booted by full path aren't in the index and won't appear here; use [`list_dir`](#snapshotlist_dir) to enumerate artifacts on disk directly.

Returns

Indexed snapshot handles, ordered by creation time descending.
```rust for h in Snapshot::list().await? { println!("{:?} — {}", h.name(), h.digest()); } ``` --- #### Snapshot::list_dir()
staticasync
```rust async fn list_dir(dir: impl AsRef) -> MicrosandboxResult> ``` Walk a directory and parse each subdirectory's manifest. Does not touch the index. Skips entries that don't look like snapshot artifacts (no `manifest.json`) and malformed artifacts.

Parameters

dirimpl AsRef<Path>
Directory to scan for artifacts.

Returns

One handle per valid artifact found.
```rust let snaps = Snapshot::list_dir("/data/snapshots").await?; println!("{} artifacts", snaps.len()); ``` --- #### Snapshot::remove()
staticasync
```rust async fn remove(path_or_name: &str, force: bool) -> MicrosandboxResult<()> ``` 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.
```rust Snapshot::remove("after-pip-install", false).await?; ``` --- #### Snapshot::reindex()
staticasync
```rust async fn reindex(dir: impl AsRef) -> MicrosandboxResult ``` 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.
```rust let n = Snapshot::reindex("/data/snapshots").await?; println!("indexed {n} snapshots"); ``` --- #### Snapshot::export()
staticasync
```rust async fn export(name_or_path: &str, out: &Path, opts: ExportOpts) -> MicrosandboxResult<()> ``` Bundle a snapshot into a `.tar.zst` archive (or plain `.tar`) at `out`. The head snapshot is verified before bundling. The recorded manifest is archived as-is, so create the snapshot with [`record_integrity()`](#record_integrity) when the archive will cross a trust boundary. See [`ExportOpts`](#exportopts) to also include ancestors and the OCI image cache.

Parameters

name_or_path&str
Snapshot name or artifact path to export.
out&Path
Output archive path. Parent directories are created if missing.
Bundling options. ExportOpts::default() writes the head snapshot only, zstd-compressed.
```rust use microsandbox::snapshot::ExportOpts; use std::path::Path; Snapshot::export( "baseline", Path::new("/tmp/baseline.tar.zst"), ExportOpts { with_parents: true, with_image: true, ..Default::default() }, ).await?; ``` --- #### Snapshot::import()
staticasync
```rust async fn import(archive_path: &Path, dest: Option<&Path>) -> MicrosandboxResult ``` 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. Recorded integrity is verified as artifacts land. 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

Handle for the head (last-listed) snapshot.
```rust use std::path::Path; let h = Snapshot::import(Path::new("/tmp/baseline.tar.zst"), None).await?; println!("imported {}", h.digest()); ``` --- ## Instance methods Methods on an opened [`Snapshot`](#snapshotopen) artifact. --- #### snap.digest()
instance
```rust 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.path()
instance
```rust fn path(&self) -> &Path ``` Path to the artifact directory holding the canonical `manifest.json` and the captured upper file.

Returns

&Path
Artifact directory path.
--- #### snap.manifest()
instance
```rust fn manifest(&self) -> &Manifest ``` The parsed [`Manifest`](#manifest): schema, format, fstype, image reference, parent, creation time, labels, and upper-layer metadata.

Returns

Parsed snapshot manifest.
```rust let snap = Snapshot::open("baseline").await?; let m = snap.manifest(); println!("{} @ {}", m.image.reference, m.image.manifest_digest); ``` --- #### snap.size_bytes()
instance
```rust fn size_bytes(&self) -> u64 ``` Apparent size of the captured upper layer in bytes (the ext4 virtual size; sparse on disk).

Returns

u64
Upper-layer apparent size in bytes.
--- #### snap.verify()
instanceasync
```rust async fn verify(&self) -> MicrosandboxResult ``` Recompute the upper layer's content hash and compare it against the manifest. Walks data extents only, so a multi-GiB sparse file with a little data verifies in milliseconds. Returns `NotRecorded` when the manifest has no integrity descriptor; errors with `SnapshotIntegrity` on mismatch.

Returns

Digest, path, and upper-layer verification status.
```rust 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"), } ``` --- ## SnapshotHandle methods Accessors and lifecycle on a [`SnapshotHandle`](#snapshothandle) (an index row). Returned by [`Snapshot::get()`](#snapshotget), [`Snapshot::list()`](#snapshotlist), and [`Snapshot::import()`](#snapshotimport). --- #### h.digest()
instance
```rust fn digest(&self) -> &str ``` Manifest digest (`sha256:hex`), the canonical identity. --- #### h.name()
instance
```rust fn name(&self) -> Option<&str> ``` Name alias, or `None` for digest-only entries. --- #### h.parent_digest()
instance
```rust 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.image_ref()
instance
```rust fn image_ref(&self) -> &str ``` Image reference the snapshot was taken from. --- #### h.format()
instance
```rust fn format(&self) -> SnapshotFormat ``` On-disk format of the upper layer.

Returns

Upper-layer format (Raw today).
--- #### h.size_bytes()
instance
```rust fn size_bytes(&self) -> Option ``` Apparent size of the upper file at index time, if recorded. --- #### h.created_at()
instance
```rust fn created_at(&self) -> chrono::NaiveDateTime ``` Snapshot creation time, parsed from the manifest. --- #### h.path()
instance
```rust fn path(&self) -> &Path ``` Local artifact directory path. --- #### h.open()
instanceasync
```rust async fn open(&self) -> MicrosandboxResult ``` Open the underlying artifact metadata, upgrading this lightweight handle to a full [`Snapshot`](#instance-methods). Equivalent to [`Snapshot::open(self.path())`](#snapshotopen).

Returns

The opened artifact.
```rust let h = Snapshot::get("baseline").await?; let snap = h.open().await?; snap.verify().await?; ``` --- #### h.remove()
instanceasync
```rust async fn remove(&self, force: bool) -> MicrosandboxResult<()> ``` Remove this snapshot. Delegates to [`Snapshot::remove(self.digest(), force)`](#snapshotremove).

Parameters

forcebool
When true, remove even if the snapshot has indexed children.
```rust let h = Snapshot::get("baseline").await?; h.remove(false).await?; ``` --- ## Sandbox entry points Snapshot-related methods that live on the sandbox builder and handle. See [Sandbox](/sdk/rust/sandbox) for the full sandbox API. --- #### .from_snapshot()
builder
```rust fn from_snapshot(self, path_or_name: impl Into) -> Self ``` `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()`](/sdk/rust/sandbox#image) and [`image_with()`](/sdk/rust/sandbox#image_with). The artifact is opened and its integrity verified at [`create()`](/sdk/rust/sandbox#create) time, not here.

Parameters

path_or_nameimpl Into<String>
Bare name resolved under the default snapshots directory, or a path to an artifact directory.
```rust let sb = Sandbox::builder("api-restored") .from_snapshot("after-pip-install") .create() .await?; ``` --- #### h.snapshot()
instanceasync
```rust async fn snapshot(&self, name: &str) -> MicrosandboxResult ``` `SandboxHandle` method. Snapshot this sandbox under a bare name in the default snapshots directory (`~/.microsandbox/snapshots//`). The sandbox must be stopped or crashed; running sandboxes are rejected with `SnapshotSandboxRunning`. Local handles only. For an explicit destination see [`snapshot_to()`](#h-snapshot_to).

Parameters

name&str
Bare snapshot name.

Returns

The created artifact handle.
```rust let h = Sandbox::get("api").await?; h.stop().await?; let snap = h.snapshot("baseline").await?; ``` --- #### h.snapshot_to()
instanceasync
```rust async fn snapshot_to(&self, path: impl AsRef) -> MicrosandboxResult ``` `SandboxHandle` method. Snapshot this sandbox to an explicit filesystem path. The sandbox must be stopped or crashed. Local handles only. For the common case of writing under the default snapshots directory see [`snapshot()`](#h-snapshot).

Parameters

pathimpl AsRef<Path>
Destination artifact directory.

Returns

The created artifact handle.
```rust let h = Sandbox::get("api").await?; h.stop().await?; let snap = h.snapshot_to("/data/snapshots/baseline").await?; ``` --- ## SnapshotBuilder Builder for a [`SnapshotConfig`](#snapshotconfig). Obtained via [`Snapshot::builder(source_sandbox)`](#snapshotbuilder). A destination is required ([`name`](#name) or [`path`](#path)); the other setters are optional. Every setter returns `Self`, so calls chain. ```rust let snap = Snapshot::builder("api") .name("after-pip-install") // bare name in default dir .label("stage", "post-deps") .force() // overwrite if it exists .record_integrity() // hash the upper layer .create() .await?; ``` --- #### .destination()
builder
```rust fn destination(self, dest: SnapshotDestination) -> Self ``` Set the artifact destination explicitly. The [`name`](#name) and [`path`](#path) setters are convenience wrappers over this.

Parameters

Name- or path-based destination.
--- #### .name()
builder
```rust fn name(self, name: impl Into) -> Self ``` Convenience: use a bare name resolved under the default snapshots directory. Sets the destination to [`SnapshotDestination::Name`](#snapshotdestination).

Parameters

nameimpl Into<String>
Bare snapshot name. Must not be empty, contain /, or start with ..
--- #### .path()
builder
```rust fn path(self, path: impl Into) -> Self ``` Convenience: write the artifact to an explicit path. Sets the destination to [`SnapshotDestination::Path`](#snapshotdestination).

Parameters

pathimpl Into<PathBuf>
Destination artifact directory.
--- #### .label()
builder
```rust fn label(self, key: impl Into, value: impl Into) -> 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()
builder
```rust fn force(self) -> Self ``` Overwrite an existing artifact at the destination. Without this, creation fails with `SnapshotAlreadyExists` if the destination directory exists. --- #### .record_integrity()
builder
```rust fn record_integrity(self) -> Self ``` Compute and record an upper-layer content-integrity hash during creation. Recorded integrity is what [`verify()`](#snap-verify) checks and what import/export rely on when crossing a trust boundary. --- #### .build()
builder
```rust fn build(self) -> MicrosandboxResult ``` Materialize the [`SnapshotConfig`](#snapshotconfig) without creating the snapshot. Errors with `InvalidConfig` if no destination was set. For capturing, use [`create`](#create) instead; it calls `build` internally.

Returns

Validated snapshot configuration.
--- #### .create()
builderasync
```rust async fn create(self) -> MicrosandboxResult ``` Build and execute the snapshot in one step. Equivalent to [`Snapshot::create(self.build()?)`](#snapshotcreate).

Returns

The created artifact handle.
--- ## Types ### SnapshotHandle
struct

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

A lightweight handle backed by a local index row. Use [`open()`](#h-open) to read the artifact metadata, and [`Snapshot::verify()`](#snap-verify) for explicit content verification. All accessors are listed under [SnapshotHandle methods](#snapshothandle-methods). | 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 | | image_ref() | `&str` | Source image reference | | format() | [`SnapshotFormat`](#snapshotformat) | On-disk upper format | | size_bytes() | `Option` | Upper file size at index time | | created_at() | `chrono::NaiveDateTime` | Creation time from the manifest | | path() | `&Path` | Local artifact directory | | open() | `Result<`[`Snapshot`](#instance-methods)`>` | Open the underlying artifact | | remove(force) | `Result<()>` | Remove this snapshot | ### SnapshotConfig
struct

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

Inputs to create a snapshot. A type alias for `SnapshotSpec`. Usually built via [`SnapshotBuilder`](#snapshotbuilder) rather than constructed directly. | Field | Type | Description | |-------|------|-------------| | source_sandbox | `String` | Name of the source sandbox; must be stopped | | destination | [`SnapshotDestination`](#snapshotdestination) | Where to write the artifact | | labels | `Vec<(String, String)>` | User-supplied labels | | force | `bool` | Overwrite an existing artifact at the destination | | record_integrity | `bool` | Compute and record upper-layer integrity at creation | ### SnapshotDestination
enum

Used by destination() · SnapshotConfig.destination

Where to place a new snapshot artifact. The builder's [`name()`](#name) and [`path()`](#path), and the handle's [`snapshot()`](#h-snapshot) / [`snapshot_to()`](#h-snapshot_to), construct this enum internally so callers rarely import it. | Variant | Fields | Description | |---------|--------|-------------| | `Name` | `String` | Bare name resolved under the default snapshots directory | | `Path` | `PathBuf` | Explicit absolute or relative path to the artifact directory | ### SnapshotFormat
enum

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) | ### ExportOpts
struct

Used by Snapshot::export()

Options for [`Snapshot::export()`](#snapshotexport). Implements `Default`; `ExportOpts::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
struct

Returned by verify()

Result of explicit snapshot verification. | Field | Type | Description | |-------|------|-------------| | digest | `String` | Snapshot manifest digest | | path | `PathBuf` | Artifact directory | | upper | [`UpperVerifyStatus`](#upperverifystatus) | Upper-layer content verification result | ### UpperVerifyStatus
enum

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
struct

Returned by manifest()

The snapshot artifact manifest, the source of truth for an artifact. 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 | | format | [`SnapshotFormat`](#snapshotformat) | On-disk format of the upper layer | | fstype | `String` | Filesystem type inside the upper (e.g. `ext4`) | | image | [`ImageRef`](#imageref) | Image the snapshot was taken from | | parent | `Option` | Parent snapshot digest, or `None` for a root | | created_at | `String` | RFC 3339 creation timestamp | | labels | `BTreeMap` | User-supplied labels, sorted by key in canonical form | | upper | [`UpperLayer`](#upperlayer) | The captured upper layer | | source_sandbox | `Option` | Best-effort name of the source sandbox (informational) | ### ImageRef
struct

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
struct

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`](#upperintegrity)`>` | Optional content integrity descriptor; `None` on local hot paths | ### UpperIntegrity
struct

Used by UpperLayer.integrity

Content integrity descriptor for the captured upper layer. | Field | Type | Description | |-------|------|-------------| | algorithm | `String` | Digest algorithm name (e.g. `msb-sparse-sha256-v1`) | | digest | `String` | Algorithm output, in `sha256:hex` form for current algorithms |