docs/sdk/go/images.mdx
<Tooltip tip="The image-cache API manages the local cache and is local-only. On microsandbox cloud, specify an OCI image when creating the sandbox and it is pulled for you."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>
Inspect and manage the local OCI image cache.
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>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
}
A metadata handle for a cached OCI image.
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()).
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 |