docs/sdk/rust/images.mdx
Inspect and manage the local OCI image cache.
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?;
async fn get_local(local: &LocalBackend, reference: &str) -> MicrosandboxResult<ImageHandle>
async fn list_local(local: &LocalBackend) -> MicrosandboxResult<Vec<ImageHandle>>
async fn inspect_local(local: &LocalBackend, reference: &str) -> MicrosandboxResult<ImageDetail>
async fn remove_local(local: &LocalBackend, reference: &str, force: bool) -> MicrosandboxResult<()>
async fn prune_local(local: &LocalBackend) -> MicrosandboxResult<ImagePruneReport>
async fn load_local(local: &LocalBackend, input: &Path, tags: Vec<String>) -> MicrosandboxResult<Vec<ImageHandle>>
async fn save_local(local: &LocalBackend, references: &[String], output: &Path, format: ImageArchiveFormat) -> MicrosandboxResult<()>
A lightweight metadata handle for a cached OCI image.
reference()
Image reference
<p className="msb-label">Returns</p>&str
size_bytes()
Total image size in bytes, when known
<p className="msb-label">Returns</p>Option<i64>
manifest_digest()
Content-addressable manifest digest
<p className="msb-label">Returns</p>Option<&str>
architecture()
Resolved architecture
<p className="msb-label">Returns</p>Option<&str>
os()
Resolved operating system
<p className="msb-label">Returns</p>Option<&str>
layer_count()
Number of layers
<p className="msb-label">Returns</p>usize
last_used_at()
Last referenced time
<p className="msb-label">Returns</p>Option<DateTime<Utc>>
created_at()
First-pulled time
<p className="msb-label">Returns</p>Option<DateTime<Utc>>
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 |