Docker Hub

Deploy Pipecat Cloud agents using Docker Hub

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)

The CLI accepts credentials as username:token and base64-encodes them before storing the image pull secret. If you create an image pull secret through the dashboard or API, the auth value must already be base64-encoded.

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.