Skip to main content
Docker Hub is a popular container registry for hosting Docker images. You can use both public and private Docker Hub repositories with Pipecat Cloud.
Even for public Docker Hub images, we recommend setting up image pull secrets due to Docker Hub’s low rate limits for unauthenticated pulls.

​
Create a Docker Hub Access Token

  1. Log in to Docker Hub
  2. Go to Account Settings > Personal access tokens
  3. Click Generate new token
  4. Name it (e.g., “pipecat-cloud”) and set permissions to Read & Write
  5. Copy and save the generated token securely

​
Configure Image Pull Secrets

Create image credentials in Pipecat Cloud for your Docker Hub account: 
pipecat cloud secrets image-pull-secret my-dockerhub-creds https://index.docker.io/v1/
When prompted, enter:
  • Username: Your Docker Hub username
  • Password: Your access token (not your account password)
You can optionally encode your credentials in base64 with the --base64encode flag. Image pull secrets are region-specific. If you’re deploying to a non-default region, specify it when creating the secret: 
pipecat cloud secrets image-pull-secret my-dockerhub-creds https://index.docker.io/v1/ --region us-east
To update your credentials, re-run the image-pull-secret command with the same name. Image pull secrets must be in the same region as the agents that use them.

​
Configure Your Deployment

Create a pcc-deploy.toml file with your Docker Hub image configuration: 
agent_name = "my-agent"
image = "your-username/my-agent:0.1"
secret_set = "my-agent-secrets"
image_credentials = "my-dockerhub-creds"

[scaling]
    min_agents = 0

​
Build and Push to Docker Hub

Build and push your agent image using the Pipecat Cloud CLI: 
# Build and push using your pcc-deploy.toml configuration
pipecat cloud docker build-push
This command automatically builds for the correct platform (linux/arm64) and pushes to your configured Docker Hub repository.

​
Deploy Your Agent

Deploy using your configured pcc-deploy.toml: 
pipecat cloud deploy

​
Making Repositories Private

If you want to use a private Docker Hub repository:
  1. Go to your repository on Docker Hub
  2. Click Settings
  3. Under Visibility, change from Public to Private
  4. Save changes
Your image pull secret handles authentication automatically — no additional configuration is needed.
For multi-region deployments, create separate image pull secrets for each region and deploy uniquely named agents to each target region.