---
url: https://ibee.ai/docs/infrastructure/container-registry
last_updated: 2026-10-20
---

> For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://ibee.ai/docs/llms.txt (full text of every page: https://ibee.ai/docs/llms-full.txt). For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ibee.ai/docs/_mcp/server.

# Container Registry

> IBEE Container Registry stores Docker images for your workspace. Create a registry, log in with an access token, push and pull images, check vulnerability scans, and clean up — with name rules, storage plans and errors.

IBEE Container Registry is a private place to store the **container images** your apps run — the packages you build with `docker build`. You push an image once, and your VMs, Kubernetes clusters and CI pipelines pull it from `registry.ibee.ai`. Every image you push is scanned for known security problems automatically.

Images are named like this:

```text
registry.ibee.ai/REGISTRY-NAME/REPOSITORY:TAG
```

| Part               | Example     | Meaning                                                       |
| ------------------ | ----------- | ------------------------------------------------------------- |
| `registry.ibee.ai` | —           | The IBEE registry host, the same for everyone                 |
| `REGISTRY-NAME`    | `acme-prod` | Your registry, created in the portal                          |
| `REPOSITORY`       | `web-api`   | One app or image name; created automatically on first push    |
| `TAG`              | `v1.4.2`    | A label for one version. Without a tag, Docker uses `latest`. |

Docker, Podman, containerd, Kubernetes and CI systems all work with it, because it follows the standard OCI (Open Container Initiative) image format.

> **Info**
>
> Container Registry is turned on per organization. If **Container Registry** isn't in your sidebar under **Infrastructure**, [contact support](/docs/support/contact-support) to request access.

## When to use Container Registry

| You want to…                                              | Use                                                   |
| --------------------------------------------------------- | ----------------------------------------------------- |
| Store images your own servers or clusters run             | A **Private** registry (this page)                    |
| Publish images anyone can pull without logging in         | A **Public** registry — you pay for their downloads   |
| Store files, backups or website assets                    | [Object Storage](/docs/infrastructure/object-storage) |
| Keep secrets such as registry tokens for deploy pipelines | [Secret Manager](/docs/tools/secret-manager)          |

## How it works

1. **Create a registry** in a workspace and choose a **storage plan** (a fixed monthly storage quota).
2. **Create an access token** — a username and password for Docker, limited to chosen registries.
3. **`docker login`, `docker push`, `docker pull`** against `registry.ibee.ai`. Each push is scanned.

## Before you begin

* Billing set up for your organization: each registry has a paid storage plan, and Billing must approve it. See [Add billing](/docs/getting-started/account-setup/add-billing).
* A workspace to hold the registry, and permission to create resources in it.
* [Docker](https://docs.docker.com/get-docker/) (or another OCI client) on the machine that pushes or pulls.

## Create a registry

### Open Container Registry

Select your organization and workspace, click **Container Registry** under **Infrastructure**, then click **Create registry**.

### Name the registry

Enter a **Registry name**. The portal checks it as you type and shows *Registry name is available.* when it's free.

* 3–48 characters: lowercase letters, numbers and hyphens.
* Start with a letter; end with a letter or number.
* Unique across all of IBEE, and it can't be changed later. A deleted registry's name is never reused.
* Reserved names are refused, including `admin`, `docker`, `harbor`, `ibee`, `library`, `private`, `public`, `registry`, `support`, `system` and any name starting with `ibee-`.

### Choose visibility

| Visibility                                     | Who can pull                                | Best for                      |
| ---------------------------------------------- | ------------------------------------------- | ----------------------------- |
| **Private** (default) — *Credentials required* | Only clients logged in with an access token | Your app and internal images  |
| **Public** — *Anonymous pulls allowed*         | Anyone, without logging in                  | Images you publish for others |

For **Public**, tick *I understand that anyone can pull images from this public registry, and I acknowledge the public download charges.* Pushing always needs a token with push permission.

### Choose a storage plan

Pick a **Storage plan**. Each plan is a fixed monthly storage quota; the page lists the plans offered to your organization with their monthly price and the outbound bandwidth price per GB. Storage uses decimal units (1 GB = 1,000,000,000 bytes).

### Create

Check the summary and click **Create registry**. The registry shows **Provisioning**, then **Active**.

If Billing doesn't approve the plan, a **Billing needs attention** dialog explains why — for example *An initial wallet top-up is required before you can create or upgrade a container registry.* Add funds under **Billing** and try again.

## Create an access token

Docker logs in with a **registry access token**, not your IBEE password or a platform API token.

### Open registry access tokens

On the registry's **Overview** tab, click **Create access token**. This opens **API Tokens → Registry access tokens** with the registry selected. (You can also open it from the organization's **API Tokens** page.)

### Fill in the token

| Field                          | What to enter                                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Token name**                 | 3–64 characters, lowercase letters, numbers and hyphens, for example `production-k8s`. Unique among the organization's active tokens. |
| **Workspace** and **Registry** | The registries the token can use                                                                                                      |
| **Registry permission**        | **Pull and push** for developers and CI that publish images; **Pull only** for servers and clusters that only run them                |
| **Token expiration**           | **7 days**, **30 days**, **90 days** (default), **1 year** or **No expiration**                                                       |

Click **Create token**.

### Save the credentials

The portal shows the **Registry username** and the **Access token**. Copy both into your password manager or CI secret store, then click **I've saved my access token**.

> **Warning**
>
> The access token is shown **once** and can't be recovered. If you lose it, rotate the token to get a new one.

## Log in, push and pull

The username contains a `$` character, so wrap it in **single quotes** on the command line:

```bash
docker login registry.ibee.ai --username 'PASTE-REGISTRY-USERNAME'
# At the Password prompt, paste the access token.
```

Docker prints `Login Succeeded`. In CI, pass the token on standard input so it never appears in logs:

```bash
printf '%s' "$IBEE_REGISTRY_TOKEN" | docker login registry.ibee.ai \
  --username "$IBEE_REGISTRY_USERNAME" --password-stdin
```

Build and push an image, or tag and push one you already have:

```bash
docker build -t registry.ibee.ai/acme-prod/web-api:v1.4.2 .
docker push registry.ibee.ai/acme-prod/web-api:v1.4.2

docker tag web-api:latest registry.ibee.ai/acme-prod/web-api:v1.4.2
docker push registry.ibee.ai/acme-prod/web-api:v1.4.2
```

Pull by tag, or by digest (the image's fixed `sha256:` fingerprint) when you need exactly the same image every time:

```bash
docker pull registry.ibee.ai/acme-prod/web-api:v1.4.2
docker pull registry.ibee.ai/acme-prod/web-api@sha256:PASTE-DIGEST
```

The **Overview** tab's **Docker instructions** section shows these commands with your registry filled in.

### Pull from Kubernetes

Create an image pull secret from a **Pull only** token and reference it in your workloads:

```bash
kubectl create secret docker-registry ibee-registry \
  --docker-server=registry.ibee.ai \
  --docker-username='PASTE-REGISTRY-USERNAME' \
  --docker-password='PASTE-ACCESS-TOKEN'
```

```yaml
spec:
  imagePullSecrets:
    - name: ibee-registry
  containers:
    - name: app
      image: registry.ibee.ai/acme-prod/web-api:v1.4.2
```

## Verify

* `docker pull` of the image you pushed succeeds from another machine.
* On the registry's **Overview** tab, the repository is listed with its artifact count, pull count and last update. Open it to see one row per image digest, with tags shown on the digest they point to.
* `https://registry.ibee.ai/v2/` answers `401 Unauthorized` to a browser. That's expected: it means the registry is reachable and needs a login.

## Review image security

Open the registry's **Security** tab. Scanning runs automatically on every push.

* **Vulnerabilities**: known security problems (CVEs — public IDs for vulnerabilities such as `CVE-2024-3094`) in the packages inside your images, counted by severity. Filter by **CVE or advisory ID**, **Severity**, **Repository**, **Image tag or digest** or **Package**. Each finding shows the installed and fixed versions and a CVSS score (0–10 severity). Click **Rescan** to scan an image again; old results stay visible until the new scan finishes.
* **SBOMs**: a software bill of materials, the list of every package in an image, in SPDX or CycloneDX format. Click **Components** to search it by name, version, license or supplier.

## Storage, quota and clean-up

Your storage plan is a hard limit. When a push would take the registry over its quota, **the push is refused**; pushes work again after you delete images or upgrade the plan.

Deleting is how you free space:

* **Pushing a new image to an existing tag** moves the tag. The previous image stays in the repository as an untagged digest and still uses storage until you delete it.
* Delete images and repositories with the API: `DELETE /container-registry/registries/{registry_id}/artifacts/{reference}?workspace_id=…` or `DELETE …/repositories/{repository_name}?confirm=true&workspace_id=…`. The portal has no delete for these, and the API is temporarily paused. If you need to free space before it resumes, contact [support](/docs/support/contact-support).

Check usage on the **Metrics** tab: storage used, storage quota, quota utilization, and outbound bandwidth over 24 hours, 7 days or 30 days.

### Upgrade the storage plan

On the **Settings** tab, choose a larger plan under **Upgrade storage plan** and click **Upgrade plan**. The tab shows **Upgrade in progress** while it's applied. Plans can only be upgraded, not downgraded.

### Change visibility

On the **Settings** tab, choose **Private** or **Public** and click **Make Private** or **Make Public**. Making a registry public requires the same acknowledgement as at creation.

## Rotate or revoke a token

The **Registry access tokens** tab lists each token with its registry, permission, creation date and status (**Active**, **Expired** or **Revoked**).

* **Rotate** issues a new access token and stops the old one immediately. Update every place that uses it.
* **Revoke** stops the token immediately. Workloads using it can no longer pull or push.

## Delete a registry

> **Warning**
>
> Deleting a registry permanently removes its repositories, images, tags and the access tokens scoped to it. The name can never be used again.

### Empty the registry

A registry must be empty before it can be deleted. Delete its repositories with the API (see [Storage, quota and clean-up](#storage-quota-and-clean-up)). While the API is paused, contact [support](/docs/support/contact-support) if you need to empty a registry.

### Delete it

In the registry list, click the delete icon on its row. In **Delete Registry**, type the registry name and click **Delete Registry**.

## Billing

* **Storage** is billed monthly for the plan you chose, whatever you actually use.
* **Outbound bandwidth** (image pulls) is billed per GB. Private and public registries have separate rates, shown on the create page and the **Settings** tab. Anonymous pulls from a public registry are billed to you.

## Use the API

> **Warning**
>
> **Temporarily paused:** managing Object Storage and Container Registry through the API, SDKs, CLI and Terraform. Until it resumes, these calls answer `404` with an empty body. That doesn't mean your resource was deleted. The portal, S3 file traffic, registry pushes and pulls, and your existing resources keep working. The API, CLI and Terraform steps for these products apply once it resumes. If you use Terraform, [read this first](/docs/api-reference/terraform#paused-object-storage-and-container-registry).

The API manages registries, tokens, repositories, images, scans and metrics. All paths start with `https://api.ibee.ai/v1/container-registry`, need the `workspace_id` query parameter, and a platform API token with `container-registry.read` or `container-registry.write`. Pushes and pulls still go through `registry.ibee.ai` with an access token.

| Task                    | Operation                                                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Check a name            | `GET /registry-names/{registry_name}/availability`                                                                                                          |
| List, create            | `GET`, `POST /registries`                                                                                                                                   |
| Get, delete             | `GET`, `DELETE /registries/{registry_id}?confirm_registry_name=NAME`                                                                                        |
| Change visibility       | `PATCH /registries/{registry_id}/visibility`                                                                                                                |
| Storage plan, upgrade   | `GET /registries/{registry_id}/package`, `POST /registries/{registry_id}/upgrade` (needs an `Idempotency-Key` header)                                       |
| Access tokens           | `GET`, `POST /registries/{registry_id}/access-tokens`; `POST …/access-tokens/{token_id}/rotate`; `DELETE …/access-tokens/{token_id}`                        |
| Repositories and images | `GET /registries/{registry_id}/repositories`; `GET …/artifacts?repository_name=REPO`; `DELETE …/artifacts/{reference}`; `POST …/artifacts/{reference}/scan` |
| Security                | `GET …/security/vulnerabilities/summary`, `GET …/security/vulnerabilities`, `GET …/security/sboms`                                                          |
| Metrics                 | `GET /registries/{registry_id}/metrics?range=24h`                                                                                                           |

Create and upgrade take the plan's SKU (stock-keeping unit, the plan's catalog code) in `billing_catalog.sku_code`. Create can return `202` while provisioning continues: poll until `observed_state` is `ACTIVE`. Lists are paged with `page` and `page_size` (at most 100). Token secrets are returned once, by create and rotate.

## Limits

|                    | Value                                             |
| ------------------ | ------------------------------------------------- |
| Registry name      | 3–48 characters; unique across IBEE; never reused |
| Token name         | 3–64 characters                                   |
| Token expiry       | 1–365 days, or no expiration; 90 days by default  |
| Storage            | The plan's quota; pushes over it are refused      |
| Plan changes       | Upgrade only                                      |
| API list page size | Up to 100                                         |

## Troubleshooting

| You see                                                                                 | What it means                                                                                     | What to do                                                                                      |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| *Use 3–48 lowercase letters, numbers, hyphens, or underscores…* or a `422` from the API | The name breaks the rules                                                                         | Use 3–48 lowercase letters, numbers and hyphens, starting with a letter. Don't use underscores. |
| *Registry name is already reserved* / not available                                     | Another registry, now or in the past, has the name                                                | Pick another name; the portal suggests some.                                                    |
| *Registry name is reserved for platform use*                                            | The name is on the reserved list or starts with `ibee-`                                           | Pick another name.                                                                              |
| **Billing needs attention**                                                             | Billing didn't approve the plan (for example a first top-up is needed, or the balance is too low) | Follow the message: add funds under **Billing**, or contact support.                            |
| `docker login` asks for the password again, or `unauthorized`                           | The username lost its `$` in the shell, or the token is wrong, revoked or expired                 | Put the username in single quotes; rotate the token if you lost it.                             |
| `denied` or `unauthorized` on `docker push`                                             | The token is **Pull only**, or doesn't cover this registry                                        | Use a **Pull and push** token for this registry.                                                |
| `docker push` fails after uploading layers, mentioning the quota                        | The registry is full                                                                              | Delete unused images or upgrade the plan.                                                       |
| Kubernetes shows `ImagePullBackOff`                                                     | The pull secret is missing or wrong, or the image name has a typo                                 | Check `imagePullSecrets` and the full image name.                                               |
| *Empty the registry before deleting it*                                                 | The registry still has repositories                                                               | Delete its repositories, then delete the registry.                                              |
| Status **Failed**                                                                       | The last change didn't complete                                                                   | Retry it, or contact support if it doesn't recover.                                             |

## Related pages

* [API Tokens](/docs/tools/api-tokens)
* [Cloud VMs](/docs/infrastructure/cloud-vms)
* [Secret Manager](/docs/tools/secret-manager): store registry tokens for deploy pipelines
* [Object Storage](/docs/infrastructure/object-storage)