Images

Inspect and prune the local OCI image cache: the images that sandbox creation has already pulled. Images can also be loaded into the cache from local archives and saved back out to archive files, so locally built images work without a registry. Everything is reached through the package-level Image value, or through an ImageHandle once you hold one.

import m "github.com/superradcompany/microsandbox/sdk/go"

Functions

Image.Get()

func (imageFactory) Get(ctx context.Context, reference string) (*ImageHandle, error)

Example

img, err := m.Image.Get(ctx, "python:3.12")
if err != nil {
    return err
}
fmt.Println(img.ManifestDigest())

Fetch one cached image by reference. Returns ErrImageNotFound when no image with that reference is present in the local cache.

Parameters

ctxcontext.Context

Cancels the lookup.

referencestring

Image reference, e.g. “python:3.12”.

Returns

*ImageHandle

Metadata handle for the cached image.

error

ErrImageNotFound when the reference is not cached.

Image.List()

func (imageFactory) List(ctx context.Context) ([]*ImageHandle, error)

Example

images, err := m.Image.List(ctx)
if err != nil {
    return err
}
for _, img := range images {
    fmt.Println(img.Reference(), img.LayerCount())
}

Return every cached image, ordered by creation time (newest first).

Parameters

ctxcontext.Context

Cancels the listing.

Returns

[]*ImageHandle

All cached image handles, newest first.

error

Non-nil on failure.

Image.Inspect()

func (imageFactory) Inspect(ctx context.Context, reference string) (*ImageDetail, error)

Example

detail, err := m.Image.Inspect(ctx, "python:3.12")
if err != nil {
    return err
}
fmt.Println(detail.Config.Entrypoint, len(detail.Layers), "layers")

Return the full detail for a cached image: the ImageHandle plus the parsed OCI config and the layer list.

Parameters

ctxcontext.Context

Cancels the inspection.

referencestring

Image reference, e.g. “python:3.12”.

Returns

*ImageDetail

Handle, OCI config, and layers.

error

ErrImageNotFound when the reference is not cached.

Image.Remove()

func (imageFactory) Remove(ctx context.Context, reference string, force bool) error

Example

if err := m.Image.Remove(ctx, "old:tag", false); err != nil {
    return err
}

Delete a cached image. When force is false, sandboxes that still reference the image cause the call to fail with ErrImageInUse.

Parameters

ctxcontext.Context

Cancels the removal.

referencestring

Image reference to delete.

forcebool

When true, remove even if sandboxes still reference it.

Returns

error

ErrImageInUse when in use and force is false.

Image.Prune()

func (imageFactory) Prune(ctx context.Context) (*ImagePruneReport, error)

Example

report, err := m.Image.Prune(ctx)
if err != nil {
    return err
}
fmt.Println(report.LayersRemoved, "layers removed")

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

Parameters

ctxcontext.Context

Cancels the prune.

Returns

*ImagePruneReport

Summary of what was reclaimed.

error

Non-nil on failure.

Image.Load()

function

func (imageFactory) Load(ctx context.Context, inputPath string, tags ...string) ([]*ImageHandle, error)

Import images from a local archive (a docker save tarball or an OCI Image Layout archive) into the cache, so locally built images can be used without a registry. Variadic tags apply extra references to the first image in the archive.

Parameters

ctxcontext.Context

Cancels the import.

inputPathstring

Path to the archive file.

tags…string

Extra references applied to the first image in the archive.

Returns

[]*ImageHandle

One handle for every image reference imported.

error

Non-nil on failure.

Example

// docker save my-image:latest -o my-image.tar
images, err := m.Image.Load(ctx, "my-image.tar", "app:local")
if err != nil {
    return err
}
for _, img := range images {
    fmt.Println(img.Reference())
}

Image.Save()

function

func (imageFactory) Save(ctx context.Context, references []string, outputPath string, format ImageArchiveFormat) error

Export one or more cached images to an archive file at outputPath. ImageArchiveDocker (the default; "" behaves the same) writes an archive loadable with docker load; ImageArchiveOCI writes an OCI Image Layout archive. Returns ErrImageNotFound when any reference is missing from the local cache.

Parameters

ctxcontext.Context

Cancels the export.

references[]string

Image references to export, e.g. “python:3.12”.

outputPathstring

Path of the archive file to write.

formatImageArchiveFormat

ImageArchiveDocker (default; "" behaves the same) or ImageArchiveOCI.

Returns

error

ErrImageNotFound when any reference is not cached.

Example

err := m.Image.Save(ctx, []string{"python:3.12"}, "python.tar", m.ImageArchiveDocker)
if err != nil {
    return err
}

Methods

Instance methods on *ImageHandle, the metadata reference returned by Image.Get and Image.List. The accessors are pure reads of cached metadata; only Remove and Inspect take a context and reach the runtime.

h.Reference()

func (h *ImageHandle) Reference() string

The image reference, e.g. "docker.io/library/python:3.12".

Returns

string

Image reference.

h.ManifestDigest()

func (h *ImageHandle) ManifestDigest() string

The content-addressable manifest digest, or empty when unknown.

Returns

string

Manifest digest, or empty.

h.Architecture()

func (h *ImageHandle) Architecture() string

The architecture resolved during the pull, or empty.

Returns

string

Architecture, or empty.

h.OS()

func (h *ImageHandle) OS() string

The operating system resolved during the pull, or empty.

Returns

string

Operating system, or empty.

h.LayerCount()

func (h *ImageHandle) LayerCount() uint

The number of layers in the image.

Returns

uint

Layer count.

h.SizeBytes()

func (h *ImageHandle) SizeBytes() *int64

The total image size in bytes, or nil when unknown.

Returns

*int64

Total size in bytes, or nil.

h.CreatedAt()

func (h *ImageHandle) CreatedAt() time.Time

When this image was first pulled. Returns the zero time.Time when unknown.

Returns

time.Time

First-pulled time, or the zero value.

h.LastUsedAt()

func (h *ImageHandle) LastUsedAt() time.Time

When this image was last referenced. Returns the zero time.Time when unknown.

Returns

time.Time

Last-referenced time, or the zero value.

h.Remove()

func (h *ImageHandle) Remove(ctx context.Context, force bool) error

Example

img, err := m.Image.Get(ctx, "old:tag")
if err != nil {
    return err
}
if err := img.Remove(ctx, false); err != nil {
    return err
}

Delete this image. Equivalent to Image.Remove(ctx, h.Reference(), force). When force is false, sandboxes that still reference the image cause the call to fail with ErrImageInUse.

Parameters

ctxcontext.Context

Cancels the removal.

forcebool

When true, remove even if sandboxes still reference it.

Returns

error

ErrImageInUse when in use and force is false.

h.Inspect()

func (h *ImageHandle) Inspect(ctx context.Context) (*ImageDetail, error)

Example

img, err := m.Image.Get(ctx, "python:3.12")
if err != nil {
    return err
}
detail, err := img.Inspect(ctx)
if err != nil {
    return err
}
fmt.Println(detail.Config.WorkingDir)

Return the full detail for this image. Equivalent to Image.Inspect(ctx, h.Reference()).

Parameters

ctxcontext.Context

Cancels the inspection.

Returns

*ImageDetail

Handle, OCI config, and layers.

error

Non-nil on failure.

Types

ImageHandle

Returned by Image.Get() · Image.List()

A lightweight metadata reference to a cached OCI image. Fields are unexported; read them through the accessor methods below. Embedded in ImageDetail.

Method	Returns	Description
Reference()	`string`	Image reference
ManifestDigest()	`string`	Content-addressable manifest digest, or empty
Architecture()	`string`	Resolved architecture, or empty
OS()	`string`	Resolved operating system, or empty
LayerCount()	`uint`	Number of layers
SizeBytes()	`*int64`	Total size in bytes, or `nil` when unknown
CreatedAt()	`time.Time`	First-pulled time, or the zero value
LastUsedAt()	`time.Time`	Last-referenced time, or the zero value
Remove(ctx, force)	`error`	Delete this image
Inspect(ctx)	`(*ImageDetail, error)`	Fetch full detail for this image

ImageDetail

Returned by Image.Inspect() · Inspect()

Bundles an ImageHandle (embedded, so all its accessors are promoted) with the parsed OCI config and layer list.

type ImageDetail struct {
    *ImageHandle
    Config *ImageConfig
    Layers []ImageLayer
}

Field	Type	Description
`*ImageHandle`	`*ImageHandle`	Embedded metadata handle (accessors promoted)
Config	`*ImageConfig`	Parsed OCI config block
Layers	`[]ImageLayer`	Layers in manifest order

ImageConfig

Used by ImageDetail.Config

The parsed OCI config block.

Field	Type	Description
Digest	`string`	Config blob digest
Env	`[]string`	Environment variables (`KEY=VALUE`)
Cmd	`[]string`	Default command
Entrypoint	`[]string`	Entrypoint
WorkingDir	`string`	Working directory
User	`string`	Default user
Labels	`map[string]string`	OCI labels
StopSignal	`string`	Stop signal

ImageLayer

Used by ImageDetail.Layers

One layer of an image manifest.

Field	Type	Description
DiffID	`string`	Uncompressed layer diff ID
BlobDigest	`string`	Compressed blob digest
MediaType	`string`	Layer media type
CompressedSizeBytes	`*int64`	Compressed size in bytes, or `nil`
ErofsSizeBytes	`*int64`	EROFS size in bytes, or `nil`
Position	`int32`	Index in the layer stack

ImagePruneReport

Returned by Image.Prune()

Summarizes the artifacts removed by Image.Prune.

Field	Type	Description
ImageRefsRemoved	`uint32`	Image references removed
ManifestsRemoved	`uint32`	Manifests removed
LayersRemoved	`uint32`	Layers removed
FsmetaRemoved	`uint32`	Fsmeta files removed
VMDKRemoved	`uint32`	VMDK files removed
BytesReclaimed	`*uint64`	Bytes reclaimed, or `nil` when unknown

ImageArchiveFormat

type

Used by Image.Save()

Selects the archive layout written by Image.Save.

type ImageArchiveFormat string

Constant	Value	Description
`ImageArchiveDocker`	`"docker"`	`docker save` compatible archive, loadable with `docker load` (the default; the empty string means the same)
`ImageArchiveOCI`	`"oci"`	OCI Image Layout archive

Getting Started

SDKs

CLI

Functions

Image.Get()

Image.List()

Image.Inspect()

Image.Remove()

Image.Prune()

Image.Load()

Image.Save()

Methods

h.Reference()

h.ManifestDigest()

h.Architecture()

h.OS()

h.LayerCount()

h.SizeBytes()

h.CreatedAt()

h.LastUsedAt()

h.Remove()

h.Inspect()

Types

ImageHandle

ImageDetail

ImageConfig

ImageLayer

ImagePruneReport

ImageArchiveFormat

​Functions

​Image.Get()

​Image.List()

​Image.Inspect()

​Image.Remove()

​Image.Prune()

​Image.Load()

​Image.Save()

​Methods

​h.Reference()

​h.ManifestDigest()

​h.Architecture()

​h.OS()

​h.LayerCount()

​h.SizeBytes()

​h.CreatedAt()

​h.LastUsedAt()

​h.Remove()

​h.Inspect()

​Types

​ImageHandle

​ImageDetail

​ImageConfig

​ImageLayer

​ImagePruneReport

​ImageArchiveFormat

Functions

Image.Get()

Image.List()

Image.Inspect()

Image.Remove()

Image.Prune()

Image.Load()

Image.Save()

Methods

h.Reference()

h.ManifestDigest()

h.Architecture()

h.OS()

h.LayerCount()

h.SizeBytes()

h.CreatedAt()

h.LastUsedAt()

h.Remove()

h.Inspect()

Types

ImageHandle

ImageDetail

ImageConfig

ImageLayer

ImagePruneReport

ImageArchiveFormat