Builder supports pulling custom container images from private registries when running Fusion locally with the Builder Desktop app. This page explains what's supported, how to configure credentials, and why private registry access works differently in Desktop versus cloud-hosted environments.
All four conditions must be true before private registry authentication is available:
- Enterprise plan: custom Docker images are an Enterprise-only feature.
- Builder Desktop app: private registry auth is not available in cloud or web environments.
- Local Docker enabled: find this in project settings under Developer → Use Local Docker.
- Image path contains
ghcr.io: only GitHub Container Registry supports private auth.
Builder currently supports authenticated pulls from one private registry. Public images from Docker Hub (docker.io) pull without credentials.
| Registry | Private auth | Notes |
GitHub Container Registry ( | ✅ Supported | Username + classic PAT with |
Docker Hub (public images) | ✅ Supported | No credentials required |
GitLab Container Registry | ❌ Not supported | Community workarounds exist, but are not officially supported |
Amazon ECR | ❌ Not supported | — |
Azure Container Registry | ❌ Not supported | — |
Docker Hub (private repos) | ❌ Not supported | — |
About community workarounds: You might find references to GITLAB_REGISTRY_USER and GITLAB_REGISTRY_PASSWORD environment variables in community threads. These variables have no effect in the current implementation and are not part of Builder's supported configuration.
Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic). Generate a new token with the read:packages scope. Fine-grained tokens are not supported; a classic PAT is required.
In your project settings, set the Container Image field to your private GHCR image path. The path must contain ghcr.io; Builder uses this to determine whether registry authentication is needed before pulling.
ghcr.io/your-org/your-image:tagOnce your image path contains ghcr.io, a GHCR Authentication section appears in project settings. Enter your GitHub username and the classic PAT from step 1.
This section is only visible when you have met all four requirements:
- Builder Desktop
- Local Docker enabled
- Builder Enterprise account
- A
ghcr.ioimage path.
It does not appear in web-based project settings.
When Fusion starts, Builder Desktop runs podman login ghcr.io with your credentials before pulling the image. If authentication fails, Builder still attempts the pull. Refer to the error from the pull step for the clearest indication of what went wrong.
Private registry auth isn't available in cloud environments because the two execution modes have different underlying architectures:
| Builder Desktop | Cloud or Web | |
Container runtime | Podman, running locally on your machine | Builder's managed infrastructure |
Registry auth | Runs podman login before pulling | No container runtime exposed to the client |
Credentials | Stay on your machine | No mechanism to supply them |
Because cloud containers run on Builder's infrastructure rather than your local machine, there's no path for user-supplied registry credentials in that environment.
Authentication section doesn't appear
Confirm all four requirements are met: you are running Builder Desktop, local Docker is enabled under Developer settings, your account is on an Enterprise plan, and the container image path contains ghcr.io.
Pull fails after authentication
Verify the PAT has the read:packages scope, is a classic token (not fine-grained), and has not expired. Also confirm the image path is correct and your GitHub account has access to the package.
Image pulls but Fusion doesn't start
Check that the image architecture matches your machine. Apple Silicon requires a linux/arm64 image or a multi-arch manifest. Open Developer → Fusion Status to see the active container image path and any runtime errors.