Images

Inspect and manage the local OCI image cache.

Image

These methods resolve the active backend with microsandbox::backend::default_backend().

Image::get()

async fn get(reference: &str) -> MicrosandboxResult<ImageHandle>

Example

let image = Image::get("python:3.12").await?;
println!("{:?}", image.manifest_digest());

Fetch one cached image by reference. Returns ImageNotFound when the reference is not present in the local cache.

Image::list()

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

Example

for image in Image::list().await? {
    println!("{}", image.reference());
}

Return every cached image, ordered by creation time with newest first.

Image::inspect()

async fn inspect(reference: &str) -> MicrosandboxResult<ImageDetail>

Example

let detail = Image::inspect("python:3.12").await?;
for layer in &detail.layers {
    println!("{} {}", layer.position, layer.diff_id);
}

Return full detail for a cached image: handle metadata, parsed OCI config fields, and layer metadata.

Image::remove()

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

Example

Image::remove("old:tag", false).await?;

Delete a cached image. When force is false, an image still referenced by one or more sandboxes returns ImageInUse.

Image::prune()

async fn prune() -> MicrosandboxResult<ImagePruneReport>

Example

let report = Image::prune().await?;
println!("{:?}", report.bytes_reclaimed);

Image::load()

staticasync

async fn load(input: &Path, tags: Vec<String>) -> MicrosandboxResult<Vec<ImageHandle>>

Import images from a local archive into the cache. Accepts docker save tarballs and OCI Image Layout archives, so locally built images can be used without going through a registry. tags applies extra references to the first image in the archive. Returns a handle for every image reference imported.

Example

// docker save my-image:latest -o my-image.tar
let images = Image::load(Path::new("my-image.tar"), vec!["app:local".into()]).await?;
for image in &images {
    println!("{}", image.reference());
}

Image::save()

staticasync

async fn save(references: &[String], output: &Path, format: ImageArchiveFormat) -> MicrosandboxResult<()>

Export cached images to an archive file. ImageArchiveFormat selects the layout: Docker (loadable with docker load) or Oci (OCI Image Layout). Returns ImageNotFound when any reference is missing from the local cache.

Example

use microsandbox::ImageArchiveFormat;

let references = vec!["python:3.12".to_string()];
Image::save(&references, Path::new("python.tar"), ImageArchiveFormat::Docker).await?;

Explicit local variants

Use these when your program owns a specific LocalBackend and should not depend on the process default backend.

use microsandbox::{Image, LocalBackend};

let backend = LocalBackend::builder()
    .home("/tmp/msb-home")
    .build()
    .await?;

let image = Image::get_local(&backend, "python:3.12").await?;
let images = Image::list_local(&backend).await?;
let detail = Image::inspect_local(&backend, image.reference()).await?;
Image::remove_local(&backend, detail.handle.reference(), false).await?;
let report = Image::prune_local(&backend).await?;

Image::get_local()

async fn get_local(local: &LocalBackend, reference: &str) -> MicrosandboxResult<ImageHandle>

Image::list_local()

async fn list_local(local: &LocalBackend) -> MicrosandboxResult<Vec<ImageHandle>>

Image::inspect_local()

async fn inspect_local(local: &LocalBackend, reference: &str) -> MicrosandboxResult<ImageDetail>

Image::remove_local()

async fn remove_local(local: &LocalBackend, reference: &str, force: bool) -> MicrosandboxResult<()>

Image::prune_local()

async fn prune_local(local: &LocalBackend) -> MicrosandboxResult<ImagePruneReport>

Image::load_local()

async fn load_local(local: &LocalBackend, input: &Path, tags: Vec<String>) -> MicrosandboxResult<Vec<ImageHandle>>

Image::save_local()

async fn save_local(local: &LocalBackend, references: &[String], output: &Path, format: ImageArchiveFormat) -> MicrosandboxResult<()>

ImageHandle

Returned by get() · list()

A lightweight metadata handle for a cached OCI image.

h.reference()

reference()

Image reference

Returns

&str

h.size_bytes()

size_bytes()

Total image size in bytes, when known

Returns

Option<i64>

h.manifest_digest()

manifest_digest()

Content-addressable manifest digest

Returns

Option<&str>

h.architecture()

architecture()

Resolved architecture

Returns

Option<&str>

h.os()

os()

Resolved operating system

Returns

Option<&str>

h.layer_count()

layer_count()

Number of layers

Returns

usize

h.last_used_at()

last_used_at()

Last referenced time

Returns

Option<DateTime<Utc>>

h.created_at()

created_at()

First-pulled time

Returns

Option<DateTime<Utc>>

Types

ImageDetail

Returned by inspect()

Full detail for a cached image.

Field	Type	Description
`handle`	`ImageHandle`	Core cached image metadata
`config`	`Option<ImageConfigDetail>`	Parsed OCI config block
`layers`	`Vec<ImageLayerDetail>`	Layers in bottom-to-top order

ImageConfigDetail

Used by ImageDetail.config

OCI image config fields extracted from the local cache.

Field	Type	Description
`digest`	`String`	Config blob digest
`env`	`Vec<String>`	Environment variables in `KEY=value` form
`cmd`	`Option<Vec<String>>`	Default command
`entrypoint`	`Option<Vec<String>>`	Image entrypoint
`working_dir`	`Option<String>`	Default working directory
`user`	`Option<String>`	Default user
`labels`	`Option<serde_json::Value>`	OCI labels
`stop_signal`	`Option<String>`	Configured stop signal

ImageLayerDetail

Used by ImageDetail.layers

Metadata for one image layer.

Field	Type	Description
`diff_id`	`String`	Uncompressed diff ID
`blob_digest`	`String`	Compressed blob digest
`media_type`	`Option<String>`	OCI media type
`compressed_size_bytes`	`Option<i64>`	Compressed blob size in bytes
`erofs_size_bytes`	`Option<i64>`	EROFS image size in bytes
`position`	`i32`	Layer position, where `0` is the bottom

ImagePruneReport

Returned by prune()

Summary of cached image data removed by Image::prune().

Field	Type	Description
`image_refs_removed`	`u32`	Cached image references removed from the local image index
`manifests_removed`	`u32`	OCI manifests removed from the local image index
`layers_removed`	`u32`	Layer records removed from the local image index
`fsmeta_removed`	`u32`	Merged fsmeta EROFS artifacts removed from disk
`vmdk_removed`	`u32`	VMDK descriptor artifacts removed from disk
`bytes_reclaimed`	`Option<u64>`	Best-effort measured bytes reclaimed from deleted artifacts

ImageArchiveFormat

enum

Used by save()

Archive layout to write when exporting images with Image::save().

Variant	Description
`Docker`	Docker `docker save` compatible archive (default)
`Oci`	OCI Image Layout archive

Getting Started

SDKs

CLI

Image

Image::get()

Image::list()

Image::inspect()

Image::remove()

Image::prune()

Image::load()

Image::save()

Image::get_local()

Image::list_local()

Image::inspect_local()

Image::remove_local()

Image::prune_local()

Image::load_local()

Image::save_local()

ImageHandle

h.reference()

h.size_bytes()

h.manifest_digest()

h.architecture()

h.os()

h.layer_count()

h.last_used_at()

h.created_at()

Types

ImageDetail

ImageConfigDetail

ImageLayerDetail

ImagePruneReport

ImageArchiveFormat

​Image

​Image::get()

​Image::list()

​Image::inspect()

​Image::remove()

​Image::prune()

​Image::load()

​Image::save()

​Image::get_local()

​Image::list_local()

​Image::inspect_local()

​Image::remove_local()

​Image::prune_local()

​Image::load_local()

​Image::save_local()

​ImageHandle

​h.reference()

​h.size_bytes()

​h.manifest_digest()

​h.architecture()

​h.os()

​h.layer_count()

​h.last_used_at()

​h.created_at()

​Types

​ImageDetail

​ImageConfigDetail

​ImageLayerDetail

​ImagePruneReport

​ImageArchiveFormat

Image

Image::get()

Image::list()

Image::inspect()

Image::remove()

Image::prune()

Image::load()

Image::save()

Image::get_local()

Image::list_local()

Image::inspect_local()

Image::remove_local()

Image::prune_local()

Image::load_local()

Image::save_local()

ImageHandle

h.reference()

h.size_bytes()

h.manifest_digest()

h.architecture()

h.os()

h.layer_count()

h.last_used_at()

h.created_at()

Types

ImageDetail

ImageConfigDetail

ImageLayerDetail

ImagePruneReport

ImageArchiveFormat