Skip to main content

Private registries

A custom image often lives in a private registry. To let Slothbox pull it, you register a registry credential on your organization and attach it to the service that needs it. Credentials are org-scoped and managed by owners (they require the settings:write permission, the same as secrets and AWS connections).

Where the secret lives​

Slothbox stores only metadata about a credential — its label, the registry host, and (for token credentials) the username. The secret token never lives in Slothbox. It is written into your organization's own AWS account as an SSM SecureString parameter, reusing the same connected account you configure for secrets and environment variables.

At bake time, and on the running box, the instance reads that parameter through its instance-profile IAM role and runs docker login to pull the image. The token is read directly from your account by the machine that needs it — it does not transit Slothbox after you save it, and the value is never returned by the API.

info

Configure a storage backend for your organization first (Settings → Secrets & variables, or PUT /organizations/{orgId}/secrets-settings). A token credential can't be saved until there's a connected AWS account to store the secret in.

Credential types​

There are two kinds of credential, depending on the registry.

Token (Docker Hub, GHCR, and similar)​

For Docker Hub, GitHub Container Registry, and most other registries, create a token credential with:

  • A label for your own reference.
  • The registry host — for example registry-1.docker.io (Docker Hub) or ghcr.io. Host only: no scheme, no path.
  • A username.
  • A secret — an access token or password. Use a scoped access token (a GitHub PAT with read:packages, a Docker Hub access token) rather than your account password.

The secret is written to your AWS account as described above; Slothbox keeps the label, host, and username so you can recognize the credential later.

ECR (Amazon Elastic Container Registry)​

For Amazon ECR, create an ecr credential with just a label and the ECR registry host (<account>.dkr.ecr.<region>.amazonaws.com). There is no token to store: the box's instance role obtains a short-lived ECR auth token via ecr:GetAuthorizationToken at pull time. This keeps ECR access entirely within your AWS account's IAM, with no long-lived secret anywhere.

Managing credentials​

Manage credentials from the web app (Settings → Registry credentials) or over the API:

# Create a token credential (the secret is stored in your AWS account, not here)
curl https://api.slothbox.dev/organizations/org_123/registry-credentials \
  -H "Authorization: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "token",
    "label": "GHCR (read packages)",
    "registry": "ghcr.io",
    "username": "acme-bot",
    "secret": "ghp_..."
  }'
# List credentials (never returns the secret)
curl https://api.slothbox.dev/organizations/org_123/registry-credentials \
  -H "Authorization: sk_..."

The response contains the credential's id (rc_…), label, registry, and type — but never the token. See the API reference for every field, plus the DELETE route to remove one. Deleting a credential also best-effort removes the stored parameter from your AWS account.

Using a credential​

Attach a credential to the custom service that needs it by setting the service's registryCredentialId to the credential's id. When the box bakes, Slothbox uses that credential to docker login before pulling the image.

Catalog images don't take a credential — they come from their public upstream registries — so registryCredentialId is only valid on custom services.

When a pull fails​

A failed docker login or image pull fails the bake: the template's bake status shows the failure, including the error Docker reported. Nothing partial is produced — fix the credential or the image reference and rebake.

Troubleshooting​

  • Authentication errors usually mean an expired or revoked token, a wrong username, or a registry host that doesn't match where the image actually lives. Update the credential (or create a new one) and rebake.
  • "Not found" errors are most often a typo in the image repository or tag — or a private image with no credential attached, since registries report unauthorized pulls of private images as not found.
  • For ECR, check that the box's instance role is allowed to pull from the repository and that the registry host's account and region match it.

Next steps​