Snapshots

Disk-only snapshots of a sandbox that is not running. 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 sandbox under a bare name in the default snapshots directory (~/.microsandbox/snapshots/<name>/). The sandbox must be stopped or crashed. 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 sandbox to an explicit filesystem path. The sandbox must be stopped or crashed. 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. The existing snapshot manifest is archived as-is; create the snapshot with recorded integrity when the archive will cross a trust boundary.

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 when present. 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>
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,
}

Snapshots currently emit Raw.

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().