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

# Registries

A **registry** is a set of encrypted Docker registry credentials stored in Modbox. When a sandbox image references a private registry, Modbox uses these credentials to pull the image at provision time.

## Supported registries

Any Docker-compatible registry works:

* **Docker Hub** — `registry-1.docker.io`
* **GitHub Container Registry** — `ghcr.io`
* **Google Artifact Registry** — `{region}-docker.pkg.dev`
* **AWS ECR** — `{account}.dkr.ecr.{region}.amazonaws.com`
* **Azure Container Registry** — `{name}.azurecr.io`
* **Self-hosted** — any registry that supports Docker auth

## Create a registry credential

```bash
POST /registries
X-Workspace-Id: your-workspace-id

{
  "name": "GitHub Container Registry",
  "server": "ghcr.io",
  "username": "your-github-username",
  "password": "ghp_your_personal_access_token",
  "email": "you@yourcompany.com"
}
```

Passwords are **encrypted at rest** using AES-256. They are never returned by the API — only the registry ID, name, server, and username are exposed.

## List registries

```bash
GET /registries
X-Workspace-Id: your-workspace-id
```

Passwords are never included in the response.

## Link a registry to an image

When creating or updating a sandbox image, pass the `registry_id`:

```bash
POST /sandbox-images
X-Workspace-Id: your-workspace-id

{
  "name": "Our Private App",
  "image": "ghcr.io/your-org/your-image",
  "tag": "latest",
  "registry_id": "uuid-of-your-registry"
}
```

Modbox will use the stored credentials to pull the image when provisioning sandboxes with this image.

## Update registry credentials

To rotate credentials (e.g. after a token expiry):

```bash
PUT /registries/{registry_id}

{
  "password": "new_token_here"
}
```

Only the fields you include will be updated.

## Delete a registry

```bash
DELETE /registries/{registry_id}
```

Deleting a registry will cause any images linked to it to fail to pull. Update the linked images to use a different registry first.

## Registry fields

| Field      | Type    | Description                            |
| ---------- | ------- | -------------------------------------- |
| `id`       | UUID    | Registry credential ID                 |
| `name`     | string  | Human-readable name                    |
| `server`   | string  | Registry server URL (e.g. `ghcr.io`)   |
| `username` | string  | Docker registry username               |
| `email`    | string  | Optional — required by some registries |
| `enabled`  | boolean | Whether this registry is active        |
| `password` | —       | Never returned by the API              |