Images

Inspect and manage the local OCI image cache.

Image

Image.get()

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

Example

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

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

Image.list()

static list(): Promise<ImageHandle[]>

Example

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

Return every cached image.

Image.inspect()

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

Example

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

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

Image.remove()

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

Example

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

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

Image.prune()

static prune(): Promise<ImagePruneReport>

Example

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

Image.load()

staticasync

static load(inputPath: string, opts?: { tag?: string }): Promise<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. tag applies an extra reference 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
const images = await Image.load("my-image.tar", { tag: "app:local" });
for (const image of images) {
  console.log(image.reference);
}

Image.save()

staticasync

static save(reference: string | readonly string[], opts: { outputPath: string; format?: "docker" | "oci" }): Promise<void>

Export one or more cached images to an archive file. format selects the archive layout: "docker" (default, loadable with docker load) or "oci" (OCI Image Layout). Throws ImageNotFoundError when any reference is not in the local cache.

Example

await Image.save("python:3.12", { outputPath: "python.tar" });
await Image.save("python:3.12", { outputPath: "python-oci.tar", format: "oci" });

Types

ImageHandle

class

Returned by get() · list() · load()

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

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

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

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

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

Getting Started

SDKs

CLI

Image

Image.get()

Image.list()

Image.inspect()

Image.remove()

Image.prune()

Image.load()

Image.save()

Types

ImageHandle

ImageDetail

ImageConfigDetail

ImageLayerDetail

ImagePruneReport

​Image

​Image.get()

​Image.list()

​Image.inspect()

​Image.remove()

​Image.prune()

​Image.load()

​Image.save()

​Types

​ImageHandle

​ImageDetail

​ImageConfigDetail

​ImageLayerDetail

​ImagePruneReport

Image

Image.get()

Image.list()

Image.inspect()

Image.remove()

Image.prune()

Image.load()

Image.save()

Types

ImageHandle

ImageDetail

ImageConfigDetail

ImageLayerDetail

ImagePruneReport