> ## Documentation Index > Fetch the complete documentation index at: https://enterprise-docs.crewai.com/llms.txt > Use this file to discover all available pages before exploring further. # Using a Private Docker Registry > Configure CrewAI Platform to pull images from your private Docker registry in air-gapped or restricted network environments # Using a Private Docker Registry For air-gapped environments or organizations with strict network policies, you can mirror all CrewAI Platform images to your private Docker registry. This guide covers pulling images from CrewAI's registry and configuring the Helm chart to use your private registry. This guide covers **container image mirroring**. For air-gapped environments, you may also need to mirror the **Python package index** for crew builds. See the [Private PyPI Registry Mirror](/configuration/private-pypi-mirror) guide. Crew automation deployments require a writable target registry. CrewAI Platform builds crew images internally and pushes them to `envVars.CREW_IMAGE_REGISTRY_OVERRIDE`. ## Prerequisites * Access to CrewAI's Docker registry at `images.crewai.com` * Your CrewAI Enterprise portal credentials (same as used for Helm registry authentication) or a service account [https://enterprise.crewai.com/crewai/team-settings/service-accounts](https://enterprise.crewai.com/crewai/team-settings/service-accounts) * A private Docker registry (ECR, ACR, GCR, Harbor, etc.) * Docker CLI installed and configured For full writable registry requirements and supported registry options, see [Requirements](/installation/requirements#container-image-registry-requirements). ## Step 1: Authenticate to CrewAI Registry Access your registry credentials via the CrewAI enterprise customer portal at `https://enterprise.crewai.com/crewai`, or create a service account in the Team Settings section for automated access. These are the same credentials used for Helm registry authentication. Replace `customer@company.com` with your actual customer email and `[YOUR_SECRET_TOKEN]` with the token provided in the customer portal. ```bash theme={null} # Export your authentication token export AUTH_TOKEN=[YOUR_SECRET_TOKEN] # Log in to the Docker registry docker login images.crewai.com \ --username customer@company.com \ --password $AUTH_TOKEN ``` ## Step 2: Pull Required Images Pull all required images from the CrewAI registry. The exact versions should match your Helm chart version. ### Current Image List (Chart v0.1.13) ```bash theme={null} # Replicated SDK (required feature and license sync) docker pull images.crewai.com/library/replicated-sdk-image:1.19.4 # CrewAI Platform application docker pull images.crewai.com/proxy/crewai/crewai/crewai-enterprise-platform:0.24.3 # BuildKit for crew builds docker pull images.crewai.com/proxy/crewai/crewai/crewai/buildkit:v2026.0408.105 # BuildKit rootless for crew builds (if buildkit.rootless.enabled=true) docker pull images.crewai.com/proxy/crewai/crewai/crewai/buildkit-rootless:v2026.0408.105 # Automation base image docker pull images.crewai.com/proxy/crewai/crewai/python-base:latest # Busybox (utility image for init containers and testing) docker pull images.crewai.com/proxy/dockerhub/library/busybox:latest # Redis (for caching and job queuing) docker pull images.crewai.com/proxy/dockerhub/library/redis:latest # Optional components (only pull if deploying these components): # PostgreSQL database (if postgres.enabled=true) docker pull images.crewai.com/proxy/crewai/dockerhub/library/postgres:16 # Internal Docker registry (if internalRegistry.enabled=true) docker pull images.crewai.com/proxy/crewai/dockerhub/library/registry:2 # MinIO object storage (if minio.enabled=true) docker pull images.crewai.com/proxy/crewai/dockerhub/minio/minio:latest # CrewAI Built-in Integration docker pull images.crewai.com/proxy/crewai/crewai/crewai-oauth:0.3.4 ``` **Version Alignment**: The image versions shown above correspond to Helm chart v0.1.13. ## Step 3: Tag Images for Your Registry Tag the pulled images with your private registry URL: ```bash theme={null} # Set your registry URL export YOUR_PRIVATE_REGISTRY="your-registry.example.com" # Tag all images docker tag images.crewai.com/library/replicated-sdk-image:1.19.4 \ $YOUR_PRIVATE_REGISTRY/crewai/replicated-sdk-image:1.19.4 docker tag images.crewai.com/proxy/crewai/crewai/crewai-enterprise-platform:0.24.3 \ $YOUR_PRIVATE_REGISTRY/crewai/crewai-enterprise-platform:0.24.3 docker tag images.crewai.com/proxy/crewai/crewai/crewai/buildkit:v2026.0408.105 \ $YOUR_PRIVATE_REGISTRY/crewai/buildkit:v2026.0408.105 docker tag images.crewai.com/proxy/crewai/crewai/crewai/buildkit-rootless:v2026.0408.105 \ $YOUR_PRIVATE_REGISTRY/crewai/buildkit-rootless:v2026.0408.105 docker tag images.crewai.com/proxy/crewai/crewai/python-base:latest \ $YOUR_PRIVATE_REGISTRY/crewai/python-base:latest docker tag images.crewai.com/proxy/dockerhub/library/busybox:latest \ $YOUR_PRIVATE_REGISTRY/crewai/busybox:latest docker tag images.crewai.com/proxy/dockerhub/library/redis:latest \ $YOUR_PRIVATE_REGISTRY/crewai/redis:latest docker tag images.crewai.com/proxy/crewai/dockerhub/library/postgres:16 \ $YOUR_PRIVATE_REGISTRY/crewai/postgres:16 docker tag images.crewai.com/proxy/crewai/dockerhub/library/registry:2 \ $YOUR_PRIVATE_REGISTRY/crewai/registry:2 docker tag images.crewai.com/proxy/crewai/dockerhub/minio/minio:latest \ $YOUR_PRIVATE_REGISTRY/crewai/minio:latest ``` ## Step 4: Push Images to Your Registry ```bash theme={null} docker push $YOUR_PRIVATE_REGISTRY/crewai/replicated-sdk-image:1.19.4 docker push $YOUR_PRIVATE_REGISTRY/crewai/crewai-enterprise-platform:0.24.3 docker push $YOUR_PRIVATE_REGISTRY/crewai/buildkit:v2026.0408.105 docker push $YOUR_PRIVATE_REGISTRY/crewai/buildkit-rootless:v2026.0408.105 docker push $YOUR_PRIVATE_REGISTRY/crewai/python-base:latest docker push $YOUR_PRIVATE_REGISTRY/crewai/busybox:latest docker push $YOUR_PRIVATE_REGISTRY/crewai/redis:latest docker push $YOUR_PRIVATE_REGISTRY/crewai/postgres:16 docker push $YOUR_PRIVATE_REGISTRY/crewai/registry:2 docker push $YOUR_PRIVATE_REGISTRY/crewai/minio:latest ``` ## Partial Registry: Crew Images Only If you only need crew-built images stored in your private registry (not platform images), you do not need to mirror the full image list above. Use `CREW_IMAGE_REGISTRY_OVERRIDE` only: ```yaml theme={null} envVars: CREW_IMAGE_REGISTRY_OVERRIDE: "your-registry.example.com/your-org" # Note: /crewai-enterprise suffix is added automatically ``` Do NOT set `global.imageRegistry` for partial-mirror deployments. `global.imageRegistry` redirects ALL platform image pulls (Redis, BuildKit, Wharf, busybox, the main application) away from `images.crewai.com`. If these images are not in your registry, every platform pod fails with `ImagePullBackOff`. Only set `global.imageRegistry` if you have mirrored every image listed in Step 2 above. | Use case | Setting to use | | ---------------------------------------------------- | ------------------------------------------------------- | | Crew images only in private registry | `CREW_IMAGE_REGISTRY_OVERRIDE` | | All platform images in private registry (air-gapped) | `global.imageRegistry` + `CREW_IMAGE_REGISTRY_OVERRIDE` | ## Step 5: Configure Helm Values Update your `values.yaml` to point to your private registry: | Registry | Authentication method in `image.registries` | | ----------------------------- | ------------------------------------------------------------------------------- | | AWS ECR | `credHelper: "ecr-login"` | | Azure ACR | `username:` (service principal app ID) / `password:` (service principal secret) | | Google GAR | `username:` (service account email) / `password:` (access token or key) | | Generic (Harbor, Artifactory) | `username` / `password` | The `credHelper` mechanism invokes an external binary at build time (used by BuildKit for crew image pushes). It does NOT enable kubelet to pull platform images — see [ECR Authentication: credHelper vs Pod Identity / IRSA](/cloud-providers/aws#ecr-authentication-credhelper-vs-pod-identity--irsa) for the distinction. ### Using a Generic Private Registry ```yaml theme={null} global: imageRegistry: "your-registry.example.com" imageNamePrefixOverride: "crewai/" image: registries: - host: "your-registry.example.com" username: "your-username" password: "your-password" envVars: CONTAINER_REGISTRY_HOSTNAME: "your-registry.example.com" CREW_IMAGE_REGISTRY_OVERRIDE: "your-registry.example.com" ``` ### AWS ECR `global.imageRegistry` redirects ALL platform image pulls — including Redis, BuildKit, Busybox, Wharf, and the main application — away from `images.crewai.com`. Only set this value if you have mirrored EVERY image listed in Step 2 above to your private registry. If you only need crew build images in your private registry, omit `global.imageRegistry` and `global.imageNamePrefixOverride` entirely and set only `CREW_IMAGE_REGISTRY_OVERRIDE`. ```yaml theme={null} global: imageRegistry: "123456789012.dkr.ecr.us-west-2.amazonaws.com" imageNamePrefixOverride: "crewai/" image: registries: - host: "123456789012.dkr.ecr.us-west-2.amazonaws.com" credHelper: "ecr-login" envVars: CONTAINER_REGISTRY_HOSTNAME: "123456789012.dkr.ecr.us-west-2.amazonaws.com" CREW_IMAGE_REGISTRY_OVERRIDE: "123456789012.dkr.ecr.us-west-2.amazonaws.com" ``` **`credHelper` limitation:** The `credHelper: "ecr-login"` configuration is used by BuildKit for building and pushing crew images. It does **not** enable kubelet to pull platform images from ECR -- kubelet does not execute credential helpers from image pull secrets. For kubelet ECR access, rely on node-level IAM (EKS worker nodes authenticate to same-account ECR automatically) or use a controller that refreshes static tokens. See [AWS Integration Guide](/cloud-providers/aws#ecr-authentication-credhelper-vs-pod-identity--irsa) for details. **`credHelper: "ecr-login"` is AWS ECR-specific.** This credential helper mechanism only works with Amazon ECR. Do NOT use `credHelper` for Azure Container Registry (ACR), Google Artifact Registry (GAR), or any other registry. Non-AWS registries require the `username`/`password` fields shown in the ACR example below. Using an unsupported `credHelper` value causes ImagePullBackOff on all pods with no clear error message. ### Azure Container Registry `global.imageRegistry` redirects ALL platform image pulls — including Redis, BuildKit, Busybox, Wharf, and the main application — away from `images.crewai.com`. Only set this value if you have mirrored EVERY image listed in Step 2 above to your private registry. If you only need crew build images in your private registry, omit `global.imageRegistry` and `global.imageNamePrefixOverride` entirely and set only `CREW_IMAGE_REGISTRY_OVERRIDE`. ```yaml theme={null} global: imageRegistry: "myregistry.azurecr.io" imageNamePrefixOverride: "crewai/" image: registries: - host: "myregistry.azurecr.io" username: "myregistry" password: "" envVars: CONTAINER_REGISTRY_HOSTNAME: "myregistry.azurecr.io" CREW_IMAGE_REGISTRY_OVERRIDE: "myregistry.azurecr.io" ``` ## Automation Script For convenience, use this script to automate the pull/tag/push process: ```bash theme={null} #!/bin/bash set -e # Configuration CREWAI_REGISTRY="images.crewai.com" YOUR_REGISTRY="your-registry.example.com" CREWAI_EMAIL="customer@company.com" # Your CrewAI customer email CREWAI_TOKEN="${AUTH_TOKEN}" # Set this environment variable from customer portal # Image list (update versions as needed) declare -A IMAGES=( ["replicated-sdk"]="library/replicated-sdk-image:1.19.4" ["platform"]="proxy/crewai/crewai/crewai-enterprise-platform:0.24.3" ["buildkit"]="proxy/crewai/crewai/crewai/buildkit:v2026.0408.105" ["buildkit-rootless"]="proxy/crewai/crewai/crewai/buildkit-rootless:v2026.0408.105" ["python-base"]="proxy/crewai/crewai/python-base:latest" ["busybox"]="proxy/dockerhub/library/busybox:latest" ["redis"]="proxy/dockerhub/library/redis:latest" ["postgres"]="proxy/crewai/dockerhub/library/postgres:16" ["registry"]="proxy/crewai/dockerhub/library/registry:2" ["minio"]="proxy/crewai/dockerhub/minio/minio:latest" ) # Target names in your registry declare -A TARGET_NAMES=( ["replicated-sdk"]="crewai/replicated-sdk-image:1.19.4" ["platform"]="crewai/crewai-enterprise-platform:0.24.3" ["buildkit"]="crewai/buildkit:v2026.0408.105" ["buildkit-rootless"]="crewai/buildkit-rootless:v2026.0408.105" ["python-base"]="crewai/python-base:latest" ["busybox"]="crewai/busybox:latest" ["redis"]="crewai/redis:latest" ["postgres"]="crewai/postgres:16" ["registry"]="crewai/registry:2" ["minio"]="crewai/minio:latest" ) echo "Authenticating to CrewAI registry..." echo "$CREWAI_TOKEN" | docker login "$CREWAI_REGISTRY" -u "$CREWAI_EMAIL" --password-stdin echo "Pulling, tagging, and pushing images..." for key in "${!IMAGES[@]}"; do source_image="${CREWAI_REGISTRY}/${IMAGES[$key]}" target_image="${YOUR_REGISTRY}/${TARGET_NAMES[$key]}" echo "Processing: $key" echo " Pulling: $source_image" docker pull "$source_image" echo " Tagging: $target_image" docker tag "$source_image" "$target_image" echo " Pushing: $target_image" docker push "$target_image" echo " ✓ Completed: $key" echo "" done echo "All images successfully mirrored to $YOUR_REGISTRY" ``` Save this script as `mirror-images.sh`, make it executable, and run: ```bash theme={null} chmod +x mirror-images.sh export AUTH_TOKEN="your-auth-token" ./mirror-images.sh ``` ## Verification After configuring your Helm values and deploying, verify the pods are pulling from your private registry: ```bash theme={null} # Verify image sources kubectl get pods -l app.kubernetes.io/name=crewai-platform -o jsonpath='{range .items[*]}{.spec.containers[*].image}{"\n"}{end}' ``` All images should show your private registry URL. ## Troubleshooting ### Image Pull Errors If you see `ImagePullBackOff` errors: 1. Verify registry credentials have been correctly set 2. Ensure image names and tags match exactly ## Related Documentation * [Private PyPI Registry Mirror](/configuration/private-pypi-mirror) — for mirroring Python packages * [Installation Guide](/installation/installation) * [Requirements](/installation/requirements) * [Post-Installation](/installation/post-installation)