Snapshots

Disk-only snapshots of a stopped sandbox. See Snapshots for concepts and walkthroughs; this page is the Rust SDK reference.

use microsandbox::{Sandbox, Snapshot, SnapshotHandle, SnapshotFormat};
use microsandbox::snapshot::ExportOpts;

SandboxBuilder

from_snapshot()

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

Boot a fresh sandbox from a snapshot artifact. Mutually exclusive with image() and image_with() — the snapshot already pins the image.

Parameters

SandboxHandle methods

snapshot()

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

Snapshot this (stopped) sandbox under a bare name in the default snapshots directory (~/.microsandbox/snapshots/<name>/). For an explicit filesystem destination see snapshot_to().

Parameters

Returns

Errors

• MicrosandboxError::SnapshotSandboxRunning — the sandbox is not stopped
• MicrosandboxError::SnapshotAlreadyExists — destination already exists (use the builder with .force() to overwrite)

snapshot_to()

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

Snapshot this (stopped) sandbox to an explicit filesystem path. For the common case of writing under the default snapshots directory see snapshot().

Parameters

Returns

Snapshot (instance)

path()

fn path(&self) -> &Path

Path to the artifact directory.

digest()

fn digest(&self) -> &str

Canonical content digest (sha256:hex) over the manifest bytes. The snapshot's identity.

manifest()

fn manifest(&self) -> &Manifest

Parsed manifest — image reference, image manifest digest, fstype, format, labels, upper-layer metadata, and optional integrity hash.

size_bytes()

fn size_bytes(&self) -> u64

Apparent size of the captured upper layer in bytes (the ext4 virtual size, sparse on disk).

verify()

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

Recompute the upper layer's content hash and compare against the manifest. Walks data extents only, so a 4 GiB sparse file with a few MB of data verifies in milliseconds. Returns NotRecorded when the manifest has no integrity hash.

Snapshot::builder

Snapshot::builder()

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

Start configuring a new snapshot. The fluent builder is the API the CLI uses internally.

let snap = Snapshot::builder("baseline")
    .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?;

Builder methods

Snapshot (static)

Snapshot::create()

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

Create a snapshot from a SnapshotConfig. Equivalent to using the builder.

Snapshot::open()

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

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.

Snapshot::get()

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

Look up a handle in the local index by name, digest, or path.

Snapshot::list()

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

List indexed snapshots from the local DB cache. External-path artifacts opened via Snapshot::open(/some/path) may not appear here unless they live under the configured snapshots directory.

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.

Snapshot::remove()

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

Remove a snapshot artifact and its index row. Refuses if the snapshot has indexed children unless force is true.

Snapshot::reindex()

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

Walk dir, upsert index rows for every artifact found, recompute parent-edge child counts. Returns the number of artifacts indexed.

Snapshot::export()

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

Bundle a snapshot into a .tar.zst archive. Computes and embeds the integrity hash in the bundled manifest if not already present.

ExportOpts

Snapshot::import()

async fn import(archive: &Path, dest: Option<&Path>) -> MicrosandboxResult<SnapshotHandle>

Unpack a snapshot archive (.tar.zst or .tar) into the snapshots directory, verifying recorded integrity on the way in. Compression is detected from magic bytes.

SnapshotHandle

Lightweight handle backed by an index row. Returned by Snapshot::list() and Snapshot::get().

let h = Snapshot::get("after-pip-install").await?;

h.digest();           // &str — sha256:...
h.name();             // Option<&str>
h.parent_digest();    // Option<&str> — None today; populated when chains land
h.image_ref();        // &str
h.format();           // SnapshotFormat::Raw | Qcow2
h.size_bytes();       // Option<u64>
h.created_at();       // chrono::NaiveDateTime
h.path();             // &Path

let snap = h.open().await?;       // verify metadata, return Snapshot
h.remove(false).await?;            // false = refuse if has children

Types

SnapshotDestination

pub enum SnapshotDestination {
    Name(String),
    Path(PathBuf),
}

Used by SnapshotBuilder::destination(). The handle methods snapshot() and snapshot_to() construct this enum internally so callers don't need to import it.

SnapshotFormat

pub enum SnapshotFormat {
    Raw,
    Qcow2,    // future
}

Always emits Raw today. The Qcow2 variant is reserved for backing-chain checkpoints.

SnapshotVerifyReport

pub struct SnapshotVerifyReport {
    pub digest: String,
    pub path: PathBuf,
    pub upper: UpperVerifyStatus,
}

pub enum UpperVerifyStatus {
    NotRecorded,
    Verified { algorithm: String, digest: String },
}

Returned by Snapshot::verify().