Images - microsandbox

Inspect, remove, and prune the local OCI image cache: the images that sandbox creation has already pulled. These APIs are exposed through the public Image class and require a local backend; cloud backends report Unsupported.

import { Image, ImageHandle } from "microsandbox";
import type { ImageDetail, ImagePruneReport } from "microsandbox";

Static · Image5

Image.get()one cached image Image.list()all cached images Image.inspect()config + layer detail Image.remove()delete a cached image Image.prune()reclaim unused data

Types

ImageHandle ImageDetail ImageConfigDetail ImageLayerDetail ImagePruneReport

Typical flow

import { Image } from "microsandbox";

for (const image of await Image.list()) {
  console.log(image.reference, image.layerCount);
}

const detail = await Image.inspect("python:3.12");
console.log(detail.config?.workingDir);

const report = await Image.prune();
console.log(report.bytesReclaimed);

Static methods

Image.get()

staticasync

static get(reference: string): Promise<ImageHandle>

Fetch one cached image by reference. Throws an image-not-found error when the reference is not present in the local cache.

Example

const image = await Image.get("python:3.12");
console.log(image.manifestDigest);

Image.list()

staticasync

static list(): Promise<ImageHandle[]>

Return every cached image.

Example

const images = await Image.list();
console.log(images.map((image) => image.reference));

Image.inspect()

staticasync

static inspect(reference: string): Promise<ImageDetail>

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

Example

const detail = await Image.inspect("python:3.12");
for (const layer of detail.layers) {
  console.log(layer.position, layer.diffId);
}

Image.remove()

staticasync

static remove(reference: string, opts?: { force?: boolean }): Promise<void>

Delete a cached image. When force is not set, an image still referenced by one or more sandboxes causes the call to fail.

Example

await Image.remove("old:tag", { force: false });

Image.prune()

staticasync

static prune(): Promise<ImagePruneReport>

Remove cached image data that is not used by any sandbox or indexed snapshot. Prune removes unused image refs, manifests that become unreachable, orphaned layers, image metadata on disk, layer EROFS artifacts, fsmeta EROFS artifacts, and VMDK descriptor artifacts. bytesReclaimed is reported when deleted files could be measured.

Example

const report = await Image.prune();
console.log(report.imageRefsRemoved, report.bytesReclaimed);

Types

ImageHandle

class

Returned by get() · list()

A lightweight metadata handle for a cached OCI image. Properties are read-only.

Property	Type	Description
`reference`	`string`	Image reference
`sizeBytes`	`number \| null`	Total image size in bytes, when known
`manifestDigest`	`string \| null`	Content-addressable manifest digest
`architecture`	`string \| null`	Resolved architecture
`os`	`string \| null`	Resolved operating system
`layerCount`	`number`	Number of layers
`lastUsedAt`	`Date \| null`	Last referenced time
`createdAt`	`Date \| null`	First-pulled time

ImageDetail

interface

Returned by inspect()

Full detail for a cached image.

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

ImageConfigDetail

interface

Used by ImageDetail.config

OCI image config fields extracted from the local cache.

Property	Type	Description
`digest`	`string`	Config blob digest
`env`	`readonly string[]`	Environment variables in `KEY=value` form
`cmd`	`readonly string[] \| null`	Default command
`entrypoint`	`readonly string[] \| null`	Image entrypoint
`workingDir`	`string \| null`	Default working directory
`user`	`string \| null`	Default user
`labels`	`Record<string, unknown> \| null`	OCI labels
`stopSignal`	`string \| null`	Configured stop signal

ImageLayerDetail

interface

Used by ImageDetail.layers

Metadata for one image layer.

Property	Type	Description
`diffId`	`string`	Uncompressed diff ID
`blobDigest`	`string`	Compressed blob digest
`mediaType`	`string \| null`	OCI media type
`compressedSizeBytes`	`number \| null`	Compressed blob size in bytes
`erofsSizeBytes`	`number \| null`	EROFS image size in bytes
`position`	`number`	Layer position, where `0` is the bottom

ImagePruneReport

interface

Returned by prune()

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

Property	Type	Description
`imageRefsRemoved`	`number`	Cached image references removed from the local image index
`manifestsRemoved`	`number`	OCI manifests removed from the local image index
`layersRemoved`	`number`	Layer records removed from the local image index
`fsmetaRemoved`	`number`	Merged fsmeta EROFS artifacts removed from disk
`vmdkRemoved`	`number`	VMDK descriptor artifacts removed from disk
`bytesReclaimed`	`number \| null`	Best-effort measured bytes reclaimed from deleted artifacts

​Static methods

​Image.get()

​Image.list()

​Image.inspect()

​Image.remove()

​Image.prune()

​Types

​ImageHandle

​ImageDetail

​ImageConfigDetail

​ImageLayerDetail

​ImagePruneReport

Static methods

Image.get()

Image.list()

Image.inspect()

Image.remove()

Image.prune()

Types

ImageHandle

ImageDetail

ImageConfigDetail

ImageLayerDetail

ImagePruneReport