docs/sdk/rust/images.mdx
Inspect, remove, prune, and import/export the local OCI image cache: the images that sandbox creation has already pulled. The ambient Image::* methods use the active default backend and return Unsupported when that backend is cloud. The *_local variants take an explicit LocalBackend and never consult ambient backend state.
use microsandbox::{Image, ImagePruneReport};
use microsandbox::Image;
for image in Image::list().await? {
println!("{} ({} layers)", image.reference(), image.layer_count());
}
let detail = Image::inspect("python:3.12").await?;
println!("{:?}", detail.config.as_ref().and_then(|c| c.working_dir.as_deref()));
let report = Image::prune().await?;
println!("removed {} refs", report.image_refs_removed);
These methods resolve the active backend with microsandbox::backend::default_backend(). They are convenient for normal local programs and fail with Unsupported when the active backend is cloud.
async fn get(reference: &str) -> MicrosandboxResult<ImageHandle>
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.
async fn list() -> MicrosandboxResult<Vec<ImageHandle>>
for image in Image::list().await? {
println!("{}", image.reference());
}
Return every cached image, ordered by creation time with newest first.
async fn inspect(reference: &str) -> MicrosandboxResult<ImageDetail>
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.
async fn remove(reference: &str, force: bool) -> MicrosandboxResult<()>
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.
async fn prune() -> MicrosandboxResult<ImagePruneReport>
let report = Image::prune().await?;
println!("{:?}", report.bytes_reclaimed);
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.
// 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());
}
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.
use microsandbox::ImageArchiveFormat;
let references = vec!["python:3.12".to_string()];
Image::save(&references, Path::new("python.tar"), ImageArchiveFormat::Docker).await?;
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?;
| Method | Signature |
|---|---|
get_local | async fn get_local(local: &LocalBackend, reference: &str) -> MicrosandboxResult<ImageHandle> |
list_local | async fn list_local(local: &LocalBackend) -> MicrosandboxResult<Vec<ImageHandle>> |
inspect_local | async fn inspect_local(local: &LocalBackend, reference: &str) -> MicrosandboxResult<ImageDetail> |
remove_local | async fn remove_local(local: &LocalBackend, reference: &str, force: bool) -> MicrosandboxResult<()> |
prune_local | async fn prune_local(local: &LocalBackend) -> MicrosandboxResult<ImagePruneReport> |
load_local | async fn load_local(local: &LocalBackend, input: &Path, tags: Vec<String>) -> MicrosandboxResult<Vec<ImageHandle>> |
save_local | async fn save_local(local: &LocalBackend, references: &[String], output: &Path, format: ImageArchiveFormat) -> MicrosandboxResult<()> |
A lightweight metadata handle for a cached OCI image.
| Method | Returns | Description |
|---|---|---|
reference() | &str | Image reference |
size_bytes() | Option<i64> | Total image size in bytes, when known |
manifest_digest() | Option<&str> | Content-addressable manifest digest |
architecture() | Option<&str> | Resolved architecture |
os() | Option<&str> | Resolved operating system |
layer_count() | usize | Number of layers |
last_used_at() | Option<DateTime<Utc>> | Last referenced time |
created_at() | Option<DateTime<Utc>> | First-pulled time |
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 |
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 |
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 |
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 |
Archive layout to write when exporting images with Image::save().
| Variant | Description |
|---|---|
Docker | Docker docker save compatible archive (default) |
Oci | OCI Image Layout archive |