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

> Inspect and manage cached images with the Ruby SDK.

See [Images](/images/overview) for image sources and caching behavior. These APIs manage the local image cache.

## Image

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

```ruby theme={null}
Microsandbox::Image.get(reference) # => ImageHandle
```

Look up a cached image.

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

<div className="msb-params">
  <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.</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">ImageHandle</span></div>
    <div className="msb-param-desc">Look up a cached image.</div>
  </div>
</div>

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

```ruby theme={null}
Microsandbox::Image.list # => Array<ImageHandle>
```

<Accordion title="Example">
  ```ruby theme={null}
  Microsandbox::Image.list.each do |image|
    puts "#{image.reference}: #{image.size_bytes} bytes"
  end
  ```
</Accordion>

List cached images.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Array\<ImageHandle></span></div>
    <div className="msb-param-desc">List cached images.</div>
  </div>
</div>

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

```ruby theme={null}
Microsandbox::Image.remove(reference, force = false) # => nil
```

Remove a cached image.

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

<div className="msb-params">
  <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.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Force removal; optional positional argument, defaults to false.</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">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

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

```ruby theme={null}
Microsandbox::Image.prune # => Hash
```

Prune unused cached images.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Hash</span></div>
    <div className="msb-param-desc">String keys: image\_refs\_removed, manifests\_removed, layers\_removed, and bytes\_reclaimed.</div>
  </div>
</div>

Ruby does not expose a standalone image pull method. Select an OCI reference using `image:` when creating a sandbox.

## ImageHandle

#### <span className="msb-recv">image.</span><span className="msb-hn">reference</span>

```ruby theme={null}
image.reference # => String
```

<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">image.</span><span className="msb-hn">size\_bytes</span>

```ruby theme={null}
image.size_bytes # => Integer | nil
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Integer | nil</span></div>
    <div className="msb-param-desc">Cached size.</div>
  </div>
</div>

#### <span className="msb-recv">image.</span><span className="msb-hn">manifest\_digest</span>

```ruby theme={null}
image.manifest_digest # => String | nil
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String | nil</span></div>
    <div className="msb-param-desc">Manifest digest.</div>
  </div>
</div>

#### <span className="msb-recv">image.</span><span className="msb-hn">architecture</span>

```ruby theme={null}
image.architecture # => String | nil
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String | nil</span></div>
    <div className="msb-param-desc">Image platform.</div>
  </div>
</div>

#### <span className="msb-recv">image.</span><span className="msb-hn">os</span>

```ruby theme={null}
image.os # => String | nil
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String | nil</span></div>
    <div className="msb-param-desc">Image platform.</div>
  </div>
</div>

#### <span className="msb-recv">image.</span><span className="msb-hn">layer\_count</span>

```ruby theme={null}
image.layer_count # => Integer
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">Number of layers.</div>
  </div>
</div>

#### <span className="msb-recv">image.</span><span className="msb-hn">created\_at</span>

```ruby theme={null}
image.created_at # => String | nil
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String | nil</span></div>
    <div className="msb-param-desc">RFC 3339 creation timestamp.</div>
  </div>
</div>