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 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
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.

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.

# 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)

# 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:

# 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

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:

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 for the distinction.

Using a Generic Private Registry

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.

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 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: "myregistry.azurecr.io"
  imageNamePrefixOverride: "crewai/"

image:
  registries:
    - host: "myregistry.azurecr.io"
      username: "myregistry"
      password: "<access-token>"

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:

#!/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:

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:

# 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:

Verify registry credentials have been correctly set
Ensure image names and tags match exactly

Private PyPI Registry Mirror — for mirroring Python packages
Installation Guide
Requirements
Post-Installation

Core Configuration

Authentication

Built-In Integrations

Advanced

Using a Private Docker Registry

Using a Private Docker Registry

Prerequisites

Step 1: Authenticate to CrewAI Registry

Step 2: Pull Required Images

Current Image List (Chart v0.1.13)

Step 3: Tag Images for Your Registry

Step 4: Push Images to Your Registry

Partial Registry: Crew Images Only

Step 5: Configure Helm Values

Using a Generic Private Registry

AWS ECR

Azure Container Registry

Automation Script

Verification

Troubleshooting

Image Pull Errors

​Using a Private Docker Registry

​Prerequisites

​Step 1: Authenticate to CrewAI Registry

​Step 2: Pull Required Images

​Current Image List (Chart v0.1.13)

​Step 3: Tag Images for Your Registry

​Step 4: Push Images to Your Registry

​Partial Registry: Crew Images Only

​Step 5: Configure Helm Values

​Using a Generic Private Registry

​AWS ECR

​Azure Container Registry

​Automation Script

​Verification

​Troubleshooting

​Image Pull Errors

​Related Documentation

Using a Private Docker Registry

Prerequisites

Step 1: Authenticate to CrewAI Registry

Step 2: Pull Required Images

Current Image List (Chart v0.1.13)

Step 3: Tag Images for Your Registry

Step 4: Push Images to Your Registry

Partial Registry: Crew Images Only

Step 5: Configure Helm Values

Using a Generic Private Registry

AWS ECR

Azure Container Registry

Automation Script

Verification

Troubleshooting

Image Pull Errors

Related Documentation