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

# Image commands

> Pull, inspect, and manage cached OCI images with the microsandbox CLI.

<Tooltip tip="Image commands manage the local cache. 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>

## msb pull

Download an image to the local cache. Shared layers are stored once.

```bash theme={null}
msb pull python
msb pull alpine
msb pull ghcr.io/my-org/my-image:v1
msb pull python --materialize flat
msb pull python --materialize all
```

Expanded form: `msb image pull`.

| Flag | Description |
| - | - |
| `-f`, `--force` | Force re-download even if cached |
| `-q`, `--quiet` | Suppress progress output |
| `--insecure` | Connect over plain HTTP instead of HTTPS |
| `--ca-certs <PATH>` | Path to a PEM file with additional CA root certificates |
| `--materialize <MODE>` | Explicitly prepare `layered`, `flat`, or `all` rootfs artifacts |

[Managed registry settings](/configuration#auth-resolution-order) take precedence over `--insecure`, `--ca-certs`, and supplied credentials. A managed TLS-only entry preserves normal credential lookup.

`layered` prepares the standard root; `flat` prepares a complete ext4 base; `all` prepares both. See [flat roots](/cli/sandbox-commands#flat-oci-rootfs).

Without `--materialize`, the configured `sandbox_defaults.oci.root_disk` selects the layout. The built-in default is layered.

<Tip>
  Pre-pulling is useful when you want sandbox creation to be instant. Without a pre-pull, the first `Sandbox.create` with a new image will block on the download.
</Tip>

## msb load

Load a Docker image archive or OCI Image Layout archive into the local microsandbox cache. References are installed and recorded individually; if a later reference fails, earlier completed references remain installed. A cache eviction during a warm import is recovered from the supplied archive.

```bash theme={null}
docker save my-image:latest | msb load
msb load --input my-image.tar
msb load --input oci-layout.tar --tag my-image:latest
```

Expanded form: `msb image load`.

| Flag | Description |
| - | - |
| `-i`, `--input <PATH>` | Read archive from a tar file instead of stdin |
| `-t`, `--tag <REF>` | Add a local image reference to the first imported image |
| `-q`, `--quiet` | Suppress output |

## msb save

Save one or more cached images as a Docker-compatible archive or OCI Image Layout archive.

```bash theme={null}
msb save --output my-image.tar my-image:latest
msb save --format oci --output my-image.oci.tar my-image:latest
msb save my-image:latest > my-image.tar
```

Expanded form: `msb image save`.

| Flag | Description |
| - | - |
| `--format <FORMAT>` | Archive format (`docker`, `oci`; default: `docker`) |
| `-o`, `--output <PATH>` | Write archive to a tar file instead of stdout |
| `-q`, `--quiet` | Suppress output |

Exports preserve image contents, but regenerated layers can change image and layer digests.

## msb images

List images in the local cache.

```bash theme={null}
msb images
msb images --format json
msb images -q               # References only
```

Expanded form: `msb image ls`.

| Flag | Description |
| - | - |
| `--format` | Output format (`json`) |
| `-q`, `--quiet` | Show only image references |

## msb image inspect

Show detailed metadata for a cached image (manifest, layers, config).

```bash theme={null}
msb image inspect python
msb image inspect python --format json
```

| Flag | Description |
| - | - |
| `--format` | Output format (`json`) |

## msb rmi

Remove one or more cached images and their layers (layers shared with other images are kept).

```bash theme={null}
msb rmi python
msb rmi alpine ubuntu   # Remove multiple
```

Expanded form: `msb image rm`.

| Flag | Description |
| - | - |
| `-f`, `--force` | Remove the image reference while preserving backing needed by sandboxes or snapshots |
| `-q`, `--quiet` | Suppress output |

## msb image prune

Remove cached images that are not used by any sandbox or indexed snapshot, then clean up dangling image artifacts.

```bash theme={null}
msb image prune
msb image prune --yes
msb image prune --format json
```

Images referenced by sandboxes or indexed snapshots are kept. `msb rmi --force` can remove a specific reference, but retains backing and cached metadata needed by those dependencies and refuses to remove a reference held by an active operation. Retained metadata files may remain after the last dependency is removed; pruning does not sweep unindexed metadata files.

Prune skips cache entries held by participating pulls, imports, exports, or sandbox creation and continues with unrelated entries. Cleanup commits bounded batches, so an error can leave earlier batches completed. Shared aliases are checked together before removing their metadata file. JSON reports include `skipped_in_use`, counting busy references, manifests, and layers. Stable lock files remain in the cache. Interrupted cleanup is recovered on a later image prune or removal, with the catalog and exact file identity checked again before deletion.

Concurrent cleanup requires every accessing CLI and SDK to participate in the lease protocol. Older clients can ignore these locks; coordinate a maintenance window when they share the same storage. Ordinary runtime and snapshot formats are unchanged. Pull and sandbox creation report an error if image ownership cannot be persisted in the catalog.

| Flag | Description |
| - | - |
| `-y`, `--yes` | Skip the confirmation prompt |
| `--format` | Output format (`json`) |
| `-q`, `--quiet` | Suppress output |

## msb registry

See [Registry commands](/cli/registry-commands) for login, logout, and stored credentials.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.