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

# Manage macOS VM images with the Orka CLI

> Orka CLI image commands: list, copy, cache, and manage macOS images for Orka VMs, including local cluster images and OCI registry sources.

## Understanding Orka images

Images are used to spin up VMs in Orka. An image contains the macOS operating system, applications, and any configurations you've set up.

**Image architecture types**

* **amd64 architecture** - Intel-based images (previously denoted by an `.img` extension). Orka 3.6 and earlier only: Orka 4.0 supports Apple silicon only and rejects new VMs that use amd64 images.
* **arm64 architecture** - Apple silicon-based images (previously denoted by an `.orkasi` extension)

> [!NOTE]
>
> Extensions are no longer required as part of an image name. The architecture is determined automatically.

**Image accessibility**

Local images are accessible from all namespaces in your Orka cluster.

## Local image commands

> [!WARNING]
>
> **Deprecated in Orka 4.0.** NFS-hosted images are deprecated and will be removed in a future Orka release. Use OCI images instead, created with [`orka vm push`](https://docs.macstadium.com/orka/orka-cli-reference/vm-lifecycle-management#orka-vm-push). In Orka 4.0, every `orka image` command prints a deprecation warning to stderr and shows `(Deprecated)` in its help. To move existing images, see [Migrate NFS Orka images to OCI format with Harbor](https://docs.macstadium.com/orka/oci-images/orka-self-service-migrating-nfs-images-to-oci-with-harbor.md). The `orka imagecache` commands aren't affected.

### orka image list

List the locally stored images in your Orka cluster. (Note, you may not have any images until you run `imagecache` or a `vm deploy` command)

**Syntax:**

```bash theme={null}
orka image list [IMAGE_NAME_1 [IMAGE_NAME_2 ...]] [--output wide|json] [flags]
```

**Options:**

```
-h, --help            Display help for list
-o, --output string   (Optional) Output format: table (default)|wide|json
```

If `--output` is not set, prints only essential information in a table format. Use `wide` for additional error information or `json` for JSON output.

**Examples:**

```bash theme={null}
# List the images stored locally in your Orka cluster
orka image list

# Check if the specified image exists locally
orka image list 90gbventurassh.img

# Check if the specified images exist locally
orka image list 90gbventurassh.img 90gbventurassh.orkasi

# List images and print output as JSON
orka image list --output json

# Show additional error information for locally stored images
orka image list --output wide

# Show additional error information for a specific image
orka image list 90gbventurassh.orkasi --output wide
```

### orka image copy

Copy the specified image and set a new name for the copy.

**Image name requirements:**

* Does not exceed 63 characters including the file extension (if set)
* Consists of lowercase alphanumeric characters, dashes (-) or periods (.)
* Must be unique to the cluster

By default, this operation also copies the description of the source image. You can explicitly change the description during this operation.

> [!NOTE]
>
> Copying an image is an async operation. To check the status: `orka image list IMAGE_COPY_NAME`

**Syntax:**

```bash theme={null}
orka image copy IMAGE_NAME IMAGE_COPY_NAME [--description 'DESCRIPTION'] [flags]
```

**Options:**

```
-d, --description string   (Optional) Custom description for the copy
-h, --help                 Display help for copy
```

**Examples:**

```bash theme={null}
# Copy an image
orka image copy 90gbventurassh.orkasi 90gbventurassh-copy.orkasi

# Copy an image with a custom description
orka image copy 90gbventurassh.orkasi 90gbventurassh-copy.orkasi --description 'user@company.com copied this image'
```

### orka3 image generate

> [!WARNING]
>
> **Removed in Orka 4.0.**`orka3 image generate` only creates Intel images and works on Orka 3.6 and earlier. In Orka 4.0 it returns an unknown-command error.

(Intel-only) Generate a new empty image with the specified size. Use an empty image to perform a fresh macOS install from ISO.

Generated images are always created as amd64 images (Intel-based images) and are accessible from all namespaces.

> [!NOTE]
>
> Generating an image is an async operation. To check the status: `orka image list GENERATED_IMAGE_NAME`

**Syntax:**

```bash theme={null}
orka3 image generate IMAGE_NAME SIZE [--description 'DESCRIPTION'] [flags]
```

**Options:**

```
-d, --description string   (Optional) Custom description for the generated image
-h, --help                 Display help for generate
```

**Examples:**

```bash theme={null}
# Generate an empty 120GB image
orka3 image generate 120gbemptyimage 120G

# Generate an empty 120GB image with a custom description
orka3 image generate 120gbemptyimage 120G --description 'user@company.com created this empty image'
```

### orka image set-description

Set a custom description for the specified image. This can be helpful to identify the owner of the image, where it originated from, or how it is used across workflows.

> [!WARNING]
>
> This operation overrides the existing description and cannot be undone.

**Syntax:**

```bash theme={null}
orka image set-description IMAGE_NAME DESCRIPTION [flags]
```

**Options:**

```
-h, --help   Display help for set-description
```

**Examples:**

```bash theme={null}
# Set a custom description for an image
orka image set-description 90gbventurassh.orkasi 'user@company.com set this description'
```

### orka image delete

Delete the specified locally stored images.

> [!WARNING]
>
> This operation cannot be undone. VMs or VM configurations that use this image are affected and might stop working as expected.

**Syntax:**

```bash theme={null}
orka image delete IMAGE_NAME [IMAGE_NAME_2 ...] [flags]
```

**Options:**

```
-h, --help   Display help for delete
```

**Examples:**

```bash theme={null}
# Delete an image from your Orka cluster
orka image delete 90gbventurassh.orkasi

# Delete multiple images
orka image delete 90gbventurassh.orkasi 90gbventurassh.img
```

## Image cache commands

Manage images stored on Orka cluster nodes. By adding images to a node before deployment of a VM using that base image, you can manage and control the delay caused by remote or even local cluster storage image pulls, providing consistent deployment times.

> [!NOTE]
>
> Image cache operations are only supported for Apple silicon nodes. The alias for `imagecache` is `ic`.

### orka imagecache add

Cache the specified image on the specified node(s). Add an image to one, a select number, or all cluster node namespace members or members of a tagged node group.

The image must be pulled in the cluster before caching it on the node(s), unless it is an OCI image. For OCI images, make sure you have the necessary credentials to pull the OCI image.

> [!NOTE]
>
> Caching an image is an async operation. To check the status: `orka imagecache info IMAGE_NAME`

The `--nodes`, `--tags`, and `--all` flags are mutually exclusive.

**Syntax:**

```bash theme={null}
orka imagecache add IMAGE_NAME [--namespace CURRENT_NAMESPACE] {--nodes | --tags | --all} [flags]
```

**Options:**

```
--all                    Cache the image on all nodes in the current namespace
-h, --help               Display help for add
--nodes string           The node(s) on which to cache the image
--tags string            The node tag(s) by which to filter nodes
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Cache an image on a specific node
orka imagecache add ghcr.io/macstadium/orka-images/sequoia:latest --nodes mini-arm-10

# Cache an image on multiple nodes
orka imagecache add ghcr.io/macstadium/orka-images/sequoia:latest --nodes mini-arm-10,mini-arm-11

# Cache an image on all nodes in the current namespace
orka imagecache add ghcr.io/macstadium/orka-images/sequoia:latest --all

# Cache an image on nodes with specific tags
orka imagecache add ghcr.io/macstadium/orka-images/sequoia:latest --tags my-tag,my-other-tag

# Cache an image on a node in a specific namespace
orka imagecache add ghcr.io/macstadium/orka-images/sequoia:latest --nodes mini-arm-10 --namespace my-namespace
```

### orka imagecache info

Display the caching status of an image across nodes. Use this to verify if images are available for deployment ("ready" status) or if the caching operation is still active ("caching" status).

**Syntax:**

```bash theme={null}
orka imagecache info IMAGE_NAME [--namespace CURRENT_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

```
-h, --help               Display help for info
-o, --output string      (Optional) Output format: table (default)|wide|json
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Display the caching status of an image
orka imagecache info sonoma-90gb-orka3-arm

# Display the caching status of an OCI image (latest is the default tag)
orka imagecache info ghcr.io/macstadium/orka-images/sonoma

# Display the caching status of an OCI image with a specific tag
orka imagecache info ghcr.io/macstadium/orka-images/sonoma:14.0
```

### orka imagecache list

List cached images across nodes. Provides information about cached images such as image tag (OCI repo pulled images only), the image-id (a unique identifier from manifest), the sparse size of the image, and the number of nodes the image is cached on.

**Syntax:**

```bash theme={null}
orka imagecache list [IMAGE_NAME_1 IMAGE_NAME_2 ...] [--namespace CURRENT_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

```
-h, --help               Display help for list
-o, --output string      (Optional) Output format: table (default)|wide|json
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# List all cached images on all nodes
orka imagecache list

# Check if a specific image is cached on any node
orka imagecache list sonoma-90gb-orka3-arm

# Check if an OCI image is cached (latest is the default tag)
orka imagecache list ghcr.io/macstadium/orka-images/sequoia

# Check if an OCI image with tag is cached
orka imagecache list ghcr.io/macstadium/orka-images/sonoma:14.0

# Check multiple images
orka imagecache list sonoma-90gb-orka3-arm ghcr.io/macstadium/orka-images/sonoma:14.0

# List all cached images as JSON
orka imagecache list --output json
```

### orka imagecache remove

> [!NOTE]
>
> Requires your Orka **cluster** to be running 3.6.3 or later, this is a server-side requirement, not a CLI one. Updating only your local `orka` CLI does not enable this command: if your cluster hasn't been upgraded to 3.6.3+, the command fails even with a current CLI. See [How to upgrade your Orka cluster](https://docs.macstadium.com/orka/orka-upgrades-and-release-notes/orka-upgrades.md) or contact [MacStadium support](mailto:support@macstadium.com) to confirm your cluster's version before troubleshooting further.

Remove a cached image from one or more nodes. Use this to free disk space on specific nodes, rotate stale images, or remove images that were cached automatically when a VM was deployed.

Removal is asynchronous: the command initiates the operation and returns immediately. Run `orka imagecache info IMAGE_NAME` to check the status.

The `--nodes`, `--tags`, and `--all` flags are mutually exclusive. Exactly one is required.

> [!WARNING]
>
> Do not remove an image while VMs are actively being deployed from it on the same node. If removal runs during the brief window between a deployment's pull and clone stages, the deployment may fail with a generic error. The race window is typically seconds, but there is no automatic protection against it. Wait for in-flight deployments to complete before removing a cached image.

**Syntax:**

```bash theme={null}
orka imagecache remove IMAGE_NAME [--namespace CURRENT_NAMESPACE] {--nodes | --tags | --all} [flags]
```

**Options:**

```
--all                    Remove the cached image from all nodes in the current namespace
-h, --help               Display help for remove
--nodes string           The node(s) from which to remove the cached image
--tags string            The node tag(s) by which to filter nodes (matches nodes with ALL listed tags)
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Remove from a specific node
orka imagecache remove ghcr.io/macstadium/orka-images/sequoia:latest --nodes mini-arm-10

# Remove from multiple nodes
orka imagecache remove ghcr.io/macstadium/orka-images/sequoia:latest --nodes mini-arm-10,mini-arm-11

# Remove from all nodes in the current namespace
orka imagecache remove ghcr.io/macstadium/orka-images/sequoia:latest --all

# Remove from nodes with specific tags
orka imagecache remove ghcr.io/macstadium/orka-images/sequoia:latest --tags my-tag,my-other-tag

# Remove from a node in a specific namespace
orka imagecache remove ghcr.io/macstadium/orka-images/sequoia:latest --nodes mini-arm-10 --namespace my-namespace
```

**Removal states:**

| State | Meaning |
| - | - |
| `Removing` | Remove job is running on the target node |
| `Failed` | Remove job failed; image stays cached. To retry, run the same command again. |

If the targeted node no longer exists, the cache entry is cleaned up immediately. If the image is not currently cached on a targeted node, the operation completes without error.

If removal reaches `Failed` and retrying does not resolve it, contact [support@macstadium.com](mailto:support@macstadium.com).

## Remote images (deprecated)

> [!WARNING]
>
> **Deprecated in Orka 4.0.** Remote images are NFS-hosted and will be removed in a future Orka release. In Orka 4.0, the `orka remote-image` commands print a deprecation warning to stderr and show `(Deprecated)` in their help. Use OCI registries for image storage, and use `orka imagecache` to load images into the cluster.

### orka remote-image list

List the available images in the remote repository or look for specific images in the remote repository.

**Syntax:**

```bash theme={null}
orka remote-image list [IMAGE_NAME_1 [IMAGE_NAME_2 ...]] [--output wide|json] [flags]
```

**Examples:**

```bash theme={null}
# List available remote images
orka remote-image list

# Check if a specific image exists remotely
orka remote-image list 90gbventurassh.img

# Check if multiple specific images exist remotely
orka remote-image list 90gbventurassh.img 90gbventurassh.orkasi
```

### orka remote-image pull

Copy an image from the remote repository and store it locally in the Orka cluster. You can keep the original name or set a new name in the local cluster storage.

> [!NOTE]
>
> Pulling a remote image is an async operation. To check the status: `orka image list PULLED_IMAGE_NAME`

**Syntax:**

```bash theme={null}
orka remote-image pull REMOTE_IMAGE_NAME [NEW_LOCAL_IMAGE] [--description 'DESCRIPTION'] [flags]
```

**Examples:**

```bash theme={null}
# Pull an image from the remote repository
orka remote-image pull 90gbventurassh.orkasi

# Pull and rename an image
orka remote-image pull 90gbventurassh.orkasi 90gbventurassh2023.orkasi

# Pull an image with a custom description
orka remote-image pull 90gbventurassh.orkasi --description 'user@company.com pulled this image'
```


## Related topics

- [Orka Engine standalone macOS VM management](https://docs.macstadium.com/orka/orka-engine/orka-engine-30.md)
- [Orka macOS virtualization platform overview](https://docs.macstadium.com/orka/orka-overview/orka-overview.md)
- [Manage Android emulators with the Orka CLI](https://docs.macstadium.com/orka/orka-cli-reference/emulator-management.md)
- [Android emulators on Orka](https://docs.macstadium.com/orka/orka-resources/android-emulators.md)
- [Deploy your first VM with the Orka CLI](https://docs.macstadium.com/orka/quick-start-guides/orka-cli-quick-start.md)


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