docs/sdk/go/images.mdx
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"
import m "github.com/superradcompany/microsandbox/sdk/go"
images, err := m.Image.List(ctx) // 1. enumerate the cache
if err != nil {
return err
}
for _, img := range images {
fmt.Println(img.Reference(), img.LayerCount())
}
report, err := m.Image.Prune(ctx) // 2. reclaim unused data
if err != nil {
return err
}
fmt.Println(report.LayersRemoved, "layers removed")
func (imageFactory) Get(ctx context.Context, reference string) (*ImageHandle, error)
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.
func (imageFactory) List(ctx context.Context) ([]*ImageHandle, error)
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).
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancels the listing.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#imagehandle">[]*ImageHandle</a></div> <div className="msb-param-desc">All cached image handles, newest first.</div> </div> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">error</span></div> <div className="msb-param-desc">Non-nil on failure.</div> </div> </div>func (imageFactory) Inspect(ctx context.Context, reference string) (*ImageDetail, error)
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.
func (imageFactory) Remove(ctx context.Context, reference string, force bool) error
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.
func (imageFactory) Prune(ctx context.Context) (*ImagePruneReport, error)
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.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>ctx</code><span className="msb-type">context.Context</span></div> <div className="msb-param-desc">Cancels the prune.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#imageprunereport">*ImagePruneReport</a></div> <div className="msb-param-desc">Summary of what was reclaimed.</div> </div> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">error</span></div> <div className="msb-param-desc">Non-nil on failure.</div> </div> </div> <Accordion title="Example">report, err := m.Image.Prune(ctx)
if err != nil {
return err
}
fmt.Println(report.LayersRemoved, "layers removed")
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.
// 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())
}
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.
err := m.Image.Save(ctx, []string{"python:3.12"}, "python.tar", m.ImageArchiveDocker)
if err != nil {
return err
}
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.
func (h *ImageHandle) Reference() string
The image reference, e.g. "docker.io/library/python:3.12".
func (h *ImageHandle) ManifestDigest() string
The content-addressable manifest digest, or empty when unknown.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">string</span></div> <div className="msb-param-desc">Manifest digest, or empty.</div> </div> </div>func (h *ImageHandle) Architecture() string
The architecture resolved during the pull, or empty.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">string</span></div> <div className="msb-param-desc">Architecture, or empty.</div> </div> </div>func (h *ImageHandle) OS() string
The operating system resolved during the pull, or empty.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">string</span></div> <div className="msb-param-desc">Operating system, or empty.</div> </div> </div>func (h *ImageHandle) LayerCount() uint
The number of layers in the image.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><span className="msb-type">uint</span></div> <div className="msb-param-desc">Layer count.</div> </div> </div>func (h *ImageHandle) SizeBytes() *int64
The total image size in bytes, or nil when unknown.
func (h *ImageHandle) CreatedAt() time.Time
When this image was first pulled. Returns the zero time.Time when unknown.
func (h *ImageHandle) LastUsedAt() time.Time
When this image was last referenced. Returns the zero time.Time when unknown.
func (h *ImageHandle) Remove(ctx context.Context, force bool) error
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.
func (h *ImageHandle) Inspect(ctx context.Context) (*ImageDetail, error)
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()).
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 |
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 |
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 |
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 |
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 |
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 |