Private registries

If your image lives in a private registry, the machine that runs it needs credentials to pull it. Attach them to the template in the Private registry section: a username and a password or access token.

Public images — Docker Hub, GHCR public packages, the Superheat base image — need nothing here.

Adding credentials

Field	Accepts	Notes
Username	up to 256 characters	Returned by the API as registry_user.
Password / token	up to 1,000 characters	Write-only. Never returned by any endpoint.

Use a scoped access token rather than an account password wherever the registry offers one — a GitHub personal access token with read:packages, an AWS ECR token, a registry-specific deploy token.

The registry host is derived from the image reference rather than entered separately. The first path segment is treated as a host when it contains a dot or a colon, so ghcr.io/acme/trainer authenticates against ghcr.io while acme/trainer authenticates against Docker Hub.

How the password is stored

The password is encrypted before it is written to the database, with an application key held as a deployment secret. It is decrypted at exactly one moment: when a deploy compiles your template into a launch, so the host can log in and pull.

It is never returned in an API response, never rendered in the console, and never included in a shared recipe. What the API exposes instead is a boolean:

{
  "registry_user": "acme-ci",
  "has_registry_password": true
}

The edit form reflects the same thing — the password field shows a placeholder reading •••••• (unchanged) when a password is already stored.

Updating and clearing

On edit, an empty password field means leave it alone. To rotate a password, type the new one. To remove the credentials entirely, send registry_password: null over the API and clear the username.

Changing the username re-mints the template's hash_id, because the username is part of the launch recipe. Changing only the password does not — the stored secret is deliberately outside the hash domain, so rotating a token does not break a pinned share link.

Sharing and duplication

The username travels with a public template

registry_user is part of the recipe and is readable by anyone who can read the template. Only the password is protected. Do not use a username that is itself sensitive, and do not make a template public assuming the registry account stays private.

Duplicating a template your organization does not own drops both the username and the password from the copy. The duplicator never had read access to the password, and inheriting ownership of the copy must not grant it. Fill in your own credentials on the copy before launching. Duplicating a template you already own keeps them.

When a pull fails

An instance whose image cannot be pulled does not reach running. Check, in order:

1. The credentials are on the template you actually deployed, not on a duplicate.
2. The token has not expired, and carries read access to that repository.
3. The image reference names the registry host, so the credentials are sent to the right place.
4. The tag exists. An [Automatic] tag resolves to a cuda-<minor> tag, which a private image almost certainly does not publish — pin a real tag.

The instance logs carry the pull error. See Logs.