> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-appcypher-sdk-runtime-bootstrap.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Images

> Go SDK - Image cache API reference

<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.

## Image

#### <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 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>

***

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

<div className="msb-tags"><span className="msb-tag is-static">function</span></div>

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

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

  <div className="msb-param">
    <div className="msb-param-key"><code>inputPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Path to the archive file.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>tags</code><span className="msb-type">...string</span></div>
    <div className="msb-param-desc">Extra references applied to the first image in the archive.</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">One handle for every image reference imported.</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">
  ```go theme={null}
  // 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())
  }
  ```
</Accordion>

***

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

<div className="msb-tags"><span className="msb-tag is-static">function</span></div>

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

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

  <div className="msb-param">
    <div className="msb-param-key"><code>references</code><span className="msb-type">\[]string</span></div>
    <div className="msb-param-desc">Image references to export, e.g. <code>"python:3.12"</code>.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>outputPath</code><span className="msb-type">string</span></div>
    <div className="msb-param-desc">Path of the archive file to write.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>format</code><a className="msb-type" href="#imagearchiveformat">ImageArchiveFormat</a></div>
    <div className="msb-param-desc"><code>ImageArchiveDocker</code> (default; <code>""</code> behaves the same) or <code>ImageArchiveOCI</code>.</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>ErrImageNotFound</code> when any reference is not cached.</div>
  </div>
</div>

<Accordion title="Example">
  ```go theme={null}
  err := m.Image.Save(ctx, []string{"python:3.12"}, "python.tar", m.ImageArchiveDocker)
  if err != nil {
      return err
  }
  ```
</Accordion>

***

## ImageHandle

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

A metadata handle for a cached OCI image.

#### <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

### 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 |

### ImageArchiveFormat

<div className="msb-tags"><span className="msb-tag is-type">type</span></div>

<p className="msb-backref">Used by <a href="#image-save">Image.Save()</a></p>

Selects the archive layout written by [`Image.Save`](#image-save).

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