docs/sdk/go/images.mdx
Inspect and prune the local OCI image cache: the images that sandbox creation has already pulled. 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)
Fetch one cached image by reference. Returns ErrImageNotFound when no image with that reference is present in the local cache.
img, err := m.Image.Get(ctx, "python:3.12")
if err != nil {
return err
}
fmt.Println(img.ManifestDigest())
func (imageFactory) List(ctx context.Context) ([]*ImageHandle, error)
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> <Accordion title="Example">images, err := m.Image.List(ctx)
if err != nil {
return err
}
for _, img := range images {
fmt.Println(img.Reference(), img.LayerCount())
}
func (imageFactory) Inspect(ctx context.Context, reference string) (*ImageDetail, error)
Return the full detail for a cached image: the ImageHandle plus the parsed OCI config and the layer list.
detail, err := m.Image.Inspect(ctx, "python:3.12")
if err != nil {
return err
}
fmt.Println(detail.Config.Entrypoint, len(detail.Layers), "layers")
func (imageFactory) Remove(ctx context.Context, reference string, force bool) error
Delete a cached image. When force is false, sandboxes that still reference the image cause the call to fail with ErrImageInUse.
if err := m.Image.Remove(ctx, "old:tag", false); err != nil {
return err
}
func (imageFactory) Prune(ctx context.Context) (*ImagePruneReport, error)
Remove cached image data that is not used by any sandbox. 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")
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
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.
img, err := m.Image.Get(ctx, "old:tag")
if err != nil {
return err
}
if err := img.Remove(ctx, false); err != nil {
return err
}
func (h *ImageHandle) Inspect(ctx context.Context) (*ImageDetail, error)
Return the full detail for this image. Equivalent to Image.Inspect(ctx, h.Reference()).
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)
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 |