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