> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  Even for public Docker Hub images, we recommend setting up image pull secrets
  due to Docker Hub's low rate limits for unauthenticated pulls.
</Note>

## Create a Docker Hub Access Token

1. Log in to [Docker Hub](https://hub.docker.com)
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:

```bash theme={null}
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:

```bash theme={null}
pipecat cloud secrets image-pull-secret my-dockerhub-creds https://index.docker.io/v1/ --region us-east
```

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

## Configure Your Deployment

Create a `pcc-deploy.toml` file with your Docker Hub image configuration:

```toml theme={null}
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:

```bash theme={null}
# 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`:

```bash theme={null}
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.

<Note>
  For multi-region deployments, create separate image pull secrets for each
  region and deploy uniquely named agents to each target region.
</Note>