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

# OCI Registry Integration

> OCI (Open Container Initiative) registry credentials are required to push and pull OCI-compatible Apple silicon-based Orka images to or from private.

## About OCI Images in Orka

OCI (Open Container Initiative) registry credentials are required to push and pull OCI-compatible Apple silicon-based Orka images to or from private repositories.

**Important:** OCI images are available only for Apple silicon-based VMs. This is the recommended modern approach for image storage and management.

**Common OCI Registries:**

* GitHub Container Registry (ghcr.io)
* Docker Hub
* Harbor
* Private registries

**Working with OCI Images:**

* To deploy a VM using an OCI image: `orka3 vm deploy --image server.com/repository/image:tag`
* To push an image to an OCI registry: `orka3 vm push VM_NAME server.com/repository/image:tag`

## Managing Registry Credentials

**Admin Only:** All registry credential operations require administrative privileges.

If `--namespace` is not set, operations default to the `orka-default` namespace. The shorthand alias for `registrycredential` is `regcred`.

### orka3 registrycredential add

Add credentials for the specified OCI registry server in the orka-default namespace or the specified namespace. Use this to add new credentials for a new server, or replace existing credentials for an existing server.

**Server Address Requirements:**

* Must include the scheme, hostname and (optionally) port
* Examples: `https://ghcr.io` or `https://10.221.188.5:30080`

If insecure communication is allowed, requests to the registry server will fall back to HTTP when HTTPS is unavailable (disabled by default).

**Syntax:**

```bash theme={null}
orka3 registrycredential add SERVER --username USERNAME {--password PASSWORD | --password-stdin} [--replace] [--allow-insecure] [--namespace TARGET_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
--allow-insecure         (Optional) Falls back to HTTP if HTTPS is unavailable
-h, --help               Display help for add
-p, --password string    Password for registry authentication
--password-stdin         Read the password from stdin
--replace                (Optional) Replaces credentials for the specified server
-u, --username string    (Required) Username for registry authentication
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Add registry credentials for GitHub Packages in a specific namespace
orka3 regcred add https://ghcr.io --username whoami --password ghp_*** --namespace orka-test

# Read the password from stdin
echo -n "$PASSWORD" | orka3 regcred add https://ghcr.io --username whoami --password-stdin

# Read the password from file over stdin
orka3 regcred add https://ghcr.io --username whoami --password-stdin < password.txt

# Add credentials for an insecure server
orka3 regcred add --allow-insecure http://10.221.188.5:30080 --username admin --password p@ssw0rd

# Replace existing credentials for GitHub Packages
orka3 regcred add --replace https://ghcr.io --username whoami --password ghp_***
```

### orka3 registrycredential list

List the OCI registry servers that have stored credentials in the orka-default namespace or the specified namespace.

**Syntax:**

```bash theme={null}
orka3 registrycredential list [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]
```

**Options:**

```bash theme={null}
-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 OCI registry servers in the 'orka-default' namespace
orka3 regcred list

# Show additional information about each registry server
orka3 regcred list --output wide --namespace orka-test
```

### orka3 registrycredential remove

Remove the authentication credentials for the specified registry server in the orka-default namespace or the specified namespace.

**Syntax:**

```bash theme={null}
orka3 registrycredential remove SERVER [--namespace TARGET_NAMESPACE] [flags]
```

**Options:**

```bash theme={null}
-h, --help               Display help for remove
-n, --namespace string   (Optional) Namespace scope (default "orka-default")
```

**Examples:**

```bash theme={null}
# Remove registry credentials for GitHub Packages in 'orka-default'
orka3 regcred remove https://ghcr.io

# Remove registry credentials for a private server in a specific namespace
orka3 regcred remove http://10.221.188.5:30080 --namespace orka-test
```

## Working with OCI Images

### Deploying VMs from OCI Images

When deploying a VM, you can specify an OCI image by its full path:

```bash theme={null}
# Deploy a VM from an OCI-compatible image in GitHub Packages
orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest

# Deploy a VM from a specific tagged version
orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:14.0
```

### Pushing Images to OCI Registries

The state of a running VM can be saved and pushed to an OCI-compatible registry. This operation is applicable only to Apple silicon-based VMs.

For more information, see the [VM Lifecycle Management](/orka/orka3-cli-reference/vm-lifecycle-management) article.

### Caching OCI Images

You can cache OCI images directly on cluster nodes without pulling them to local storage first:

```bash theme={null}
# Cache an OCI image on specific nodes
orka3 imagecache add ghcr.io/my-organization/orka-images/orka-arm:latest --nodes mini-arm-10

# Check caching status of an OCI image
orka3 imagecache info ghcr.io/my-organization/orka-images/orka-arm:latest
```