Images - microsandbox

Image is the static namespace for two related things: configuring an explicit rootfs source for a sandbox (Image.oci, Image.bind, Image.disk), and managing the local OCI image cache that sandbox creation pulls into (get, list, inspect, remove, prune). Cache operations require a local backend. See Sandbox for the image= and pull_policy= creation kwargs.

from microsandbox import Image

Typical flow

from microsandbox import Image, Sandbox

# Pull happens implicitly on creation
async with await Sandbox.create("api", image="python:3.12") as sb:
    await sb.exec("python", ["-V"])

# Later, inspect and prune the local cache
for image in await Image.list():
    print(image.reference, image.layer_count)

report = await Image.prune()
print(f"reclaimed {report.bytes_reclaimed} bytes")

Source factory

These static methods return an ImageSource you can pass as the image= kwarg to Sandbox.create(). A plain string also works (image="python:3.12"); use the factory when you need OCI-only options like the writable upper size, or to be explicit about a bind or disk source.

Image.oci()

@staticmethod
def oci(reference: str, *, upper_size_mib: int | None = None) -> ImageSource

Example

sb = await Sandbox.create(
    "api",
    image=Image.oci("python:3.12", upper_size_mib=8192),
)

Create an OCI image rootfs source. Use upper_size_mib to size the writable overlay upper layer; otherwise the default applies.

Parameters

referencestr

OCI image reference, e.g. “python:3.12”.

upper_size_mibint | None

Writable overlay upper size in MiB. None keeps the default.

Returns

ImageSource

Rootfs source for image=.

Image.bind()

@staticmethod
def bind(path: str) -> ImageSource

Example

sb = await Sandbox.create("api", image=Image.bind("/srv/rootfs"))

Create a rootfs source that binds a host directory as the guest root filesystem.

Parameters

pathstr

Host directory to use as the rootfs.

Returns

ImageSource

Rootfs source for image=.

Image.disk()

@staticmethod
def disk(path: str, *, fstype: str | None = None) -> ImageSource

Example

sb = await Sandbox.create(
    "api",
    image=Image.disk("/data/root.qcow2", fstype="ext4"),
)

Create a rootfs source backed by a disk image. The format is inferred from the file extension. Pass fstype when the filesystem type cannot be auto-detected.

Parameters

pathstr

Path to the disk image (e.g. .qcow2, .raw, .vmdk).

fstypestr | None

Filesystem type, e.g. “ext4”. None auto-detects.

Returns

ImageSource

Rootfs source for image=.

Cache management

These static methods inspect and prune images already pulled into the local OCI cache. They require a local backend; on a cloud backend they raise UnsupportedError.

Image.get()

@staticmethod
async def get(reference: str) -> ImageHandle

Example

handle = await Image.get("python:3.12")
print(handle.reference, handle.layer_count)

Fetch one cached image by reference. Raises ImageNotFoundError when the image is not present in the local cache.

Parameters

referencestr

Image reference to look up.

Returns

ImageHandle

Handle to the cached image.

Image.list()

@staticmethod
async def list() -> list[ImageHandle]

Example

for image in await Image.list():
    print(image.reference, image.size_bytes)

Return every cached image.

Returns

list[ImageHandle]

All cached image handles.

Image.inspect()

@staticmethod
async def inspect(reference: str) -> ImageDetail

Example

detail = await Image.inspect("python:3.12")
print(detail.handle.reference)
for layer in detail.layers:
    print(layer.position, layer.diff_id)

Return handle metadata plus the parsed OCI config and per-layer detail.

Parameters

referencestr

Image reference to inspect.

Returns

ImageDetail

Handle, OCI config, and layers.

Image.remove()

@staticmethod
async def remove(reference: str, *, force: bool = False) -> None

Example

await Image.remove("python:3.12", force=True)

Delete a cached image. When force is False, an image still referenced by one or more sandboxes raises ImageInUseError; pass force=True to remove it anyway.

Parameters

referencestr

Image reference to delete.

forcebool

Remove even if still referenced. Default False.

Image.prune()

@staticmethod
async def prune() -> ImagePruneReport

Example

report = await Image.prune()
print(f"{report.layers_removed} layers, {report.bytes_reclaimed} bytes")

Remove cached image data that is not used by any sandbox or indexed snapshot. The returned report counts the removed refs, manifests, layers, fsmeta files, and VMDK files, plus any measured bytes reclaimed.

Returns

ImagePruneReport

Counts of removed data and bytes reclaimed.

Types

ImageSource

Returned by oci() · bind() · disk()

Explicit rootfs image source. Build one with Image.oci(), Image.bind(), or Image.disk(), then pass it as the image= kwarg to Sandbox.create(). A frozen dataclass; treat its fields as opaque.

Field	Type	Description
`_type`	`str`	Source kind: `"oci"`, `"bind"`, or `"disk"`
`_path`	`str \| None`	Host path for `bind` / `disk` sources
`_reference`	`str \| None`	OCI reference for `oci` sources
`_upper_size_mib`	`int \| None`	Writable overlay upper size in MiB (OCI only)
`_fstype`	`str \| None`	Filesystem type for `disk` sources
`_format`	`DiskImageFormat` `\| None`	Disk image format (inferred from extension)

ImageHandle

Returned by get() · list()

A lightweight handle to a cached OCI image, returned by Image.get() and Image.list(). Properties are read-only attributes; the two methods are async.

Property / Method	Type	Description
`reference`	`str`	Image reference
`size_bytes`	`int \| None`	Total size in bytes, or `None` when unknown
`manifest_digest`	`str \| None`	Content-addressable manifest digest
`architecture`	`str \| None`	Resolved architecture
`os`	`str \| None`	Resolved operating system
`layer_count`	`int`	Number of layers
`last_used_at`	`float \| None`	Last referenced time, milliseconds since epoch
`created_at`	`float \| None`	First-pulled time, milliseconds since epoch
`await inspect()`	`ImageDetail`	Fetch full detail for this image
`await remove(*, force=False)`	`None`	Delete this image (raises `ImageInUseError` unless `force`)

ImageDetail

Returned by inspect() · ImageHandle.inspect()

Full detail for a cached image: the core handle, the parsed OCI config block, and per-layer metadata.

Property	Type	Description
`handle`	`ImageHandle`	Core cached image metadata
`config`	`ImageConfigDetail` `\| None`	Parsed OCI config block
`layers`	`list[ImageLayerDetail]`	Layers in bottom-to-top order

ImageConfigDetail

Used by ImageDetail.config

OCI image config fields extracted from the local cache.

Property	Type	Description
`digest`	`str`	Config blob digest
`env`	`list[str]`	Environment variables (`KEY=value`)
`cmd`	`list[str] \| None`	Default command
`entrypoint`	`list[str] \| None`	Image entrypoint
`working_dir`	`str \| None`	Default working directory
`user`	`str \| None`	Default user
`labels`	`dict[str, Any] \| None`	OCI labels
`stop_signal`	`str \| None`	Configured stop signal

ImageLayerDetail

Used by ImageDetail.layers

Metadata for a single image layer.

Property	Type	Description
`diff_id`	`str`	Uncompressed layer diff id
`blob_digest`	`str`	Compressed blob digest
`media_type`	`str \| None`	Layer media type
`compressed_size_bytes`	`int \| None`	Compressed size in bytes
`erofs_size_bytes`	`int \| None`	Size of the generated EROFS sidecar in bytes
`position`	`int`	Layer position (bottom to top)

ImagePruneReport

Returned by prune()

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

Property	Type	Description
`image_refs_removed`	`int`	Number of image refs removed
`manifests_removed`	`int`	Number of manifests removed
`layers_removed`	`int`	Number of layer blobs removed
`fsmeta_removed`	`int`	Number of fsmeta sidecar files removed
`vmdk_removed`	`int`	Number of VMDK files removed
`bytes_reclaimed`	`int \| None`	Measured bytes reclaimed, or `None` when not measured

DiskImageFormat

Used by ImageSource._format

Disk image container format. A StrEnum, so the string values are accepted directly.

Value	Description
`"qcow2"`	QEMU copy-on-write v2
`"raw"`	Raw block image
`"vmdk"`	VMware disk image

Errors

Image operations raise these typed exceptions, all subclasses of MicrosandboxError.

Exception	Raised when
`ImageNotFoundError`	The image reference could not be resolved in the local cache
`ImageInUseError`	The image is still referenced by one or more sandboxes (and `force` was not set)
`ImagePullFailedError`	An image pull failed
`UnsupportedError`	Cache operations were attempted on a backend that lacks a local cache

​Source factory

​Image.oci()

​Image.bind()

​Image.disk()

​Cache management

​Image.get()

​Image.list()

​Image.inspect()

​Image.remove()

​Image.prune()

​Types

​ImageSource

​ImageHandle

​ImageDetail

​ImageConfigDetail

​ImageLayerDetail

​ImagePruneReport

​DiskImageFormat

​Errors

Source factory

Image.oci()

Image.bind()

Image.disk()

Cache management

Image.get()

Image.list()

Image.inspect()

Image.remove()

Image.prune()

Types

ImageSource

ImageHandle

ImageDetail

ImageConfigDetail

ImageLayerDetail

ImagePruneReport

DiskImageFormat

Errors