# Private container images

Source: https://docs.oiy.ai/docs/private-images

Use account-owned pull credentials for an exact OCI repository.



<div className="preview-banner">
  <strong>DEPLOYMENT-DEPENDENT CAPABILITY</strong>

  The current preview source supports private images through the same account interface in both region tiers. Private pulls require the updated control plane and regional gateway. Runtime and image compatibility still apply.
</div>

## 1. Define the repository scope [#1-define-the-repository-scope]

Image access belongs to **one exact repository**, such as `ghcr.io/team/model`. Enter a fully qualified repository without `https://`, a tag, or a digest.

| Access scope         | Image reference                      | Matches? |
| -------------------- | ------------------------------------ | -------- |
| `ghcr.io/team/model` | `ghcr.io/team/model:v1`              | Yes      |
| `ghcr.io/team/model` | The same repository pinned by digest | Yes      |
| `ghcr.io/team/model` | `ghcr.io/team/another-model:v1`      | No       |

Tags and digests do not expand access to neighboring repositories. An account can store up to 20 distinct repository entries. For Docker Hub library images, the canonical form includes `docker.io/library/…`.

## 2. Save pull-only credentials [#2-save-pull-only-credentials]

In console **Settings**, add image access with a name, repository, username, and a pull-only credential scoped to that repository. Verified email is required when saving or rotating access.

Reads return names, repositories, revisions, and linked services. Usernames and passwords are write-only. Do not put the token in a service command, application environment, template, notebook output, or a chat message.

## 3. Deploy the image [#3-deploy-the-image]

Choose the matching image reference in your service or template. Oiy selects access by repository automatically; the public service specification does not need a supplier credential ID.

The selected runtime uses the credential for image pulling. It is not mounted into the application workspace or exposed as an application environment variable. Saving access does not prove the image has already been pulled successfully; inspect service events and startup logs.

## Rotate credentials [#rotate-credentials]

Read the current revision and replace the credential through Settings or the API. The repository is immutable; create a separate entry for a different repository.

Rotation affects future launches without stopping an already-running service. An operation that has already been admitted retains the credential version captured for it. Check a new launch after rotation before removing access at the registry provider.

## Remove access [#remove-access]

Pause all linked services and wait until they are confirmed `sleeping` with no allocation. A stopped-looking error alone does not prove cleanup has completed. Removing an access entry leaves images and workspace files intact.

A service bound to removed access cannot silently switch to anonymous pulling. Restore the repository access or change the service image before starting it again.

## CLI and Python [#cli-and-python]

Install the [source-distributed clients](/docs/developers) first. Supply `OIY_REGISTRY_USERNAME` and `OIY_REGISTRY_PASSWORD` through your local environment or secret store. Do not put their values in command arguments.

```sh
oiy registry save --name "Model images" --repository ghcr.io/team/model --request-id model-access-001
oiy registry list
```

Rotation uses `--id REGISTRY_ID --revision CURRENT_REVISION` with the unchanged repository. Removal uses `oiy registry delete REGISTRY_ID --revision CURRENT_REVISION --yes` and a request ID, after confirmed pause.

The Python client exposes `registries()`, `save_registry(spec, registry_id=..., revision=..., idempotency_key=...)`, and `delete_registry(id, revision, key)`. Build the secret fields from your environment rather than literal source strings.

MCP `oiy_save_registry` reads named local environment variables prefixed `OIY_REGISTRY_`; raw credential values are not tool arguments. `oiy_registries` returns metadata, and registry removal uses `oiy_delete` with a revision and ID confirmation.

[Image access API](/docs/api/images) · [Container requirements](/docs/services/configuration)