> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Images

> Go SDK - Image cache API reference

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`](#imagehandle) once you hold one.

```go theme={null}
import m "github.com/superradcompany/microsandbox/sdk/go"
```

<p className="msb-label" id="typical-flow">Typical flow</p>

```go theme={null}
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")
```

## Functions

#### <span className="msb-recv">Image.</span><span className="msb-hn">Get()</span>

```go theme={null}
func (imageFactory) Get(ctx context.Context, reference string) (*ImageHandle, error)
```

<Accordion title="Example">
  ```go theme={null}
  img, err := m.Image.Get(ctx, "python:3.12")
  if err != nil {
      return err
  }
  fmt.Println(img.ManifestDigest())
  ```
</Accordion>

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

<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 lookup.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>reference</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Image reference, e.g. <code>"python:3.12"</code>.</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">Metadata handle for the cached image.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">error</span></div>
    <div className="msb-param-desc"><code>ErrImageNotFound</code> when the reference is not cached.</div>
  </div>
</div>

#### <span className="msb-recv">Image.</span><span className="msb-hn">List()</span>

```go theme={null}
func (imageFactory) List(ctx context.Context) ([]*ImageHandle, error)
```

<Accordion title="Example">
  ```go theme={null}
  images, err := m.Image.List(ctx)
  if err != nil {
      return err
  }
  for _, img := range images {
      fmt.Println(img.Reference(), img.LayerCount())
  }
  ```
</Accordion>

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>

#### <span className="msb-recv">Image.</span><span className="msb-hn">Inspect()</span>

```go theme={null}
func (imageFactory) Inspect(ctx context.Context, reference string) (*ImageDetail, error)
```

<Accordion title="Example">
  ```go theme={null}
  detail, err := m.Image.Inspect(ctx, "python:3.12")
  if err != nil {
      return err
  }
  fmt.Println(detail.Config.Entrypoint, len(detail.Layers), "layers")
  ```
</Accordion>

Return the full detail for a cached image: the [`ImageHandle`](#imagehandle) plus the parsed OCI config and the layer list.

<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 inspection.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>reference</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Image reference, e.g. <code>"python:3.12"</code>.</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="#imagedetail">\*ImageDetail</a></div>
    <div className="msb-param-desc">Handle, OCI config, and layers.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">error</span></div>
    <div className="msb-param-desc"><code>ErrImageNotFound</code> when the reference is not cached.</div>
  </div>
</div>

#### <span className="msb-recv">Image.</span><span className="msb-hn">Remove()</span>

```go theme={null}
func (imageFactory) Remove(ctx context.Context, reference string, force bool) error
```

<Accordion title="Example">
  ```go theme={null}
  if err := m.Image.Remove(ctx, "old:tag", false); err != nil {
      return err
  }
  ```
</Accordion>

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

<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 removal.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>reference</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Image reference to delete.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">When <code>true</code>, remove even if sandboxes still reference it.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">error</span></div>
    <div className="msb-param-desc"><code>ErrImageInUse</code> when in use and <code>force</code> is false.</div>
  </div>
</div>

#### <span className="msb-recv">Image.</span><span className="msb-hn">Prune()</span>

```go theme={null}
func (imageFactory) Prune(ctx context.Context) (*ImagePruneReport, error)
```

<Accordion title="Example">
  ```go theme={null}
  report, err := m.Image.Prune(ctx)
  if err != nil {
      return err
  }
  fmt.Println(report.LayersRemoved, "layers removed")
  ```
</Accordion>

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>

## Methods

Instance methods on [`*ImageHandle`](#imagehandle), the metadata reference returned by [`Image.Get`](#image-get) and [`Image.List`](#image-list). The accessors are pure reads of cached metadata; only `Remove` and `Inspect` take a context and reach the runtime.

#### <span className="msb-recv">h.</span><span className="msb-hn">Reference()</span>

```go theme={null}
func (h *ImageHandle) Reference() string
```

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

<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">Image reference.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">ManifestDigest()</span>

```go theme={null}
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>

#### <span className="msb-recv">h.</span><span className="msb-hn">Architecture()</span>

```go theme={null}
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>

#### <span className="msb-recv">h.</span><span className="msb-hn">OS()</span>

```go theme={null}
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>

#### <span className="msb-recv">h.</span><span className="msb-hn">LayerCount()</span>

```go theme={null}
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>

#### <span className="msb-recv">h.</span><span className="msb-hn">SizeBytes()</span>

```go theme={null}
func (h *ImageHandle) SizeBytes() *int64
```

The total image size in bytes, or `nil` 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">\*int64</span></div>
    <div className="msb-param-desc">Total size in bytes, or <code>nil</code>.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">CreatedAt()</span>

```go theme={null}
func (h *ImageHandle) CreatedAt() time.Time
```

When this image was first pulled. Returns the zero `time.Time` 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">time.Time</span></div>
    <div className="msb-param-desc">First-pulled time, or the zero value.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">LastUsedAt()</span>

```go theme={null}
func (h *ImageHandle) LastUsedAt() time.Time
```

When this image was last referenced. Returns the zero `time.Time` 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">time.Time</span></div>
    <div className="msb-param-desc">Last-referenced time, or the zero value.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">Remove()</span>

```go theme={null}
func (h *ImageHandle) Remove(ctx context.Context, force bool) error
```

<Accordion title="Example">
  ```go theme={null}
  img, err := m.Image.Get(ctx, "old:tag")
  if err != nil {
      return err
  }
  if err := img.Remove(ctx, false); err != nil {
      return err
  }
  ```
</Accordion>

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

<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 removal.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">bool</span></div>
    <div className="msb-param-desc">When <code>true</code>, remove even if sandboxes still reference it.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">error</span></div>
    <div className="msb-param-desc"><code>ErrImageInUse</code> when in use and <code>force</code> is false.</div>
  </div>
</div>

#### <span className="msb-recv">h.</span><span className="msb-hn">Inspect()</span>

```go theme={null}
func (h *ImageHandle) Inspect(ctx context.Context) (*ImageDetail, error)
```

<Accordion title="Example">
  ```go theme={null}
  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)
  ```
</Accordion>

Return the full detail for this image. Equivalent to [`Image.Inspect(ctx, h.Reference())`](#image-inspect).

<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 inspection.</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="#imagedetail">\*ImageDetail</a></div>
    <div className="msb-param-desc">Handle, OCI config, and layers.</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>

## Types

### ImageHandle

<p className="msb-backref">Returned by <a href="#image-get">Image.Get()</a> · <a href="#image-list">Image.List()</a></p>

A lightweight metadata reference to a cached OCI image. Fields are unexported; read them through the accessor methods below. Embedded in [`ImageDetail`](#imagedetail).

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

### ImageDetail

<p className="msb-backref">Returned by <a href="#image-inspect">Image.Inspect()</a> · <a href="#h-inspect">Inspect()</a></p>

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

```go theme={null}
type ImageDetail struct {
    *ImageHandle
    Config *ImageConfig
    Layers []ImageLayer
}
```

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

### ImageConfig

<p className="msb-backref">Used by <a href="#imagedetail">ImageDetail.Config</a></p>

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

<p className="msb-backref">Used by <a href="#imagedetail">ImageDetail.Layers</a></p>

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

<p className="msb-backref">Returned by <a href="#image-prune">Image.Prune()</a></p>

Summarizes the artifacts removed by [`Image.Prune`](#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 |