# Configure OCI Repository

Configure your OCI client to connect to and authenticate to a Nexus OCI repository. Note that you must create an OCI repository in Nexus before configuration. For more details, see [Create an OCI repository](https://help.sonatype.com/en/create-an-oci-repository.html "Create an OCI Repository").

OCI clients communicate with a registry through the OCI Distribution API at the `/v2/` endpoint and complete a bearer-token handshake. When a client first connects to the registry, the registry may respond with a `401` unauthorized status and a `WWW-Authenticate` header. This header tells the client where to request a bearer token and which permissions are required. The client then requests a scoped bearer token from the authentication service and retries the original request with the token.

OCI-compatible clients, such as Docker, Podman, Helm, and ORAS, handle this authentication flow automatically after you log in. These clients cache your login credentials locally, typically in `~/.docker/config.json` or a container's `auth.json` file and use those credentials to request bearer tokens when needed.

## Log in

To login to any of the OCI compatible clients, use the repository host (no scheme, no path) as the registry address. Replace `<NexusURL>` with your hostname which may be in the format of `example.nexus.com`.

- Docker

```bash
docker login <NexusURL>
```

- Podman

```bash
podman login <NexusURL>
```

- Helm

```bash
helm registry login <NexusURL> -u <USERNAME> -p <PASSWORD>
```

- ORAS

```bash
oras login <NexusURL> -u <USERNAME> -p <PASSWORD>
```

- Crane

```bash
crane auth login <NexusURL> -u <USERNAME> -p <PASSWORD>
```

- Skopeo

```bash
skopeo login <NexusURL>
```

Sonatype recommends user token login for all CLI and CI usage. User token is required when single sign-on (SSO) is enabled as an interactive password cannot be used. To generate a user token, navigate to _Account_ → _Access_ → _Usertoken_. Use the _name code_ as your username and _pass code_ as your password.

Nexus Repository Cloud does not support anonymous access and Self-hosted deployments may support anonymous pulls when configured.

## Routing

Routing determines how OCI clients resolve a repository endpoint. Nexus Repository supports path-based, subdomain, and port-based addresses to expose the same OCI `/v2/` registry API through deployment-specific URL patterns.

| Mode   | Client Address                                   | Availability                                                |
|--------|--------------------------------------------------|------------------------------------------------------------|
| Path-based | `<NexusURL>/<repository-name>/<image>`        | All deployments. This is the only mode in Nexus Repository Cloud. |
| Subdomain | `<repository-name>.<NexusURL>/<image>`          | Self-hosted, Nexus Repository Pro only. Requires the subdomain-routing license entitlement. |
| Port, also called Other Connectors | `<NexusURL>:<port>/<image>`          | Self-hosted deployments.                                       |

**Note**

In self-hosted deployments, OCI repositories authenticate `/v2/` through the _OCI Bearer Token Realm_. Administrators can enable this realm under _Administration_ → _Security_ → _Realms_. In Nexus Repository Cloud, Sonatype manages Realms. For more details, refer [Realms documentation](https://help.sonatype.com/en/realms.html "Realms").

## TLS

Nexus Repository Cloud is served over HTTPS with a valid certificate, so `--plain-http` or insecure-registry configuration is not required.

For self-hosted HTTP connectors, Helm and ORAS accept `--plain-http`. Docker requires the host to be listed under `insecure-registries`.