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

$
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"
>
}

List registries

$
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:

$
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):

$
PUT /registries/{registry_id}
$
$
{
>
  "password": "new_token_here"
>
}

Only the fields you include will be updated.

Delete a registry

$
DELETE /registries/{registry_id}

Registry fields