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

> Python SDK - Image cache API reference

The Python SDK exposes local OCI image-cache operations through `Image`.
These APIs inspect and prune images that have already been pulled by sandbox
creation. `Image` also remains the namespace for explicit rootfs source
configuration such as `Image.oci(...)`, `Image.bind(...)`, and `Image.disk(...)`.

```python theme={null}
from microsandbox import Image
```

## Image

***

#### Image.get()

```python theme={null}
async def Image.get(reference: str) -> ImageHandle
```

Fetch one cached image by reference. Raises `ImageNotFoundError` when the image
is not present in the local cache.

***

#### Image.list()

```python theme={null}
async def Image.list() -> list[ImageHandle]
```

Return every cached image, ordered newest first.

```python theme={null}
images = await Image.list()
for image in images:
    print(image.reference, image.layer_count)
```

***

#### Image.inspect()

```python theme={null}
async def Image.inspect(reference: str) -> ImageDetail
```

Return handle metadata plus parsed OCI config and layer details.

***

#### Image.remove()

```python theme={null}
async def Image.remove(reference: str, *, force: bool = False) -> None
```

Delete a cached image. When `force` is false, sandboxes still referencing the
image raise `ImageInUseError`.

***

#### Image.prune()

```python theme={null}
async def Image.prune() -> ImagePruneReport
```

Remove cached image data that is not used by any sandbox or indexed snapshot.
The returned report includes the count of removed refs, manifests, layers,
fsmeta files, VMDK files, and any measured bytes reclaimed.

## ImageHandle

Returned by `Image.get()` and `Image.list()`.

| Property / Method           | Type            | Description                                      |
| --------------------------- | --------------- | ------------------------------------------------ |
| `reference`                 | `str`           | Image reference                                  |
| `manifest_digest`           | `str \| None`   | Content-addressable manifest digest              |
| `architecture`              | `str \| None`   | Resolved architecture                            |
| `os`                        | `str \| None`   | Resolved operating system                        |
| `layer_count`               | `int`           | Number of layers                                 |
| `size_bytes`                | `int \| None`   | Total size, or `None` when unknown               |
| `created_at`                | `float \| None` | First-pulled time as milliseconds since epoch    |
| `last_used_at`              | `float \| None` | Last referenced time as milliseconds since epoch |
| `await remove(force=False)` | `None`          | Delete this image                                |
| `await inspect()`           | `ImageDetail`   | Fetch full detail for this image                 |

## ImageDetail

| Property | Type                        | Description                   |
| -------- | --------------------------- | ----------------------------- |
| `handle` | `ImageHandle`               | Core cached image metadata    |
| `config` | `ImageConfigDetail \| None` | Parsed OCI config block       |
| `layers` | `list[ImageLayerDetail]`    | Layers in bottom-to-top order |

### ImageConfigDetail

| Property      | Type                     |
| ------------- | ------------------------ |
| `digest`      | `str`                    |
| `env`         | `list[str]`              |
| `cmd`         | `list[str] \| None`      |
| `entrypoint`  | `list[str] \| None`      |
| `working_dir` | `str \| None`            |
| `user`        | `str \| None`            |
| `labels`      | `dict[str, Any] \| None` |
| `stop_signal` | `str \| None`            |

### ImageLayerDetail

| Property                | Type          |
| ----------------------- | ------------- |
| `diff_id`               | `str`         |
| `blob_digest`           | `str`         |
| `media_type`            | `str \| None` |
| `compressed_size_bytes` | `int \| None` |
| `erofs_size_bytes`      | `int \| None` |
| `position`              | `int`         |

### ImagePruneReport

| Property             | Type          |
| -------------------- | ------------- |
| `image_refs_removed` | `int`         |
| `manifests_removed`  | `int`         |
| `layers_removed`     | `int`         |
| `fsmeta_removed`     | `int`         |
| `vmdk_removed`       | `int`         |
| `bytes_reclaimed`    | `int \| None` |