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

# pipecat cloud docker

> pipecat cloud docker builds, tags, and pushes agent Docker images to container registries for Pipecat Cloud deployments.

The `docker` command provides utilities for building, tagging, and pushing Docker images to container registries. This command automatically parses registry information from your deployment configuration and supports both Docker Hub and custom registries.

## build-push

Build, tag, and push a Docker image for your agent deployment. This command reads configuration from your `pcc-deploy.toml` file to automatically determine registry settings, image names, and versions.

**Usage:**

```shell theme={null}
pipecat cloud docker build-push [ARGS] [OPTIONS]
```

**Arguments:**

**agent-name** `string`

Name of the agent to build image for. If not provided, uses the repository
name from the `image` field in your `pcc-deploy.toml` file (e.g., `my-agent`
from `myusername/my-agent:1.0`), or `agent_name` when there is no `image`.

**Options:**

**--config-file** `string`

Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.

**Registry Configuration:**

**--registry / -r** `string`

Registry type to push to. Supported values: `dockerhub`, `custom`. When not
specified, automatically detected from the `image` field in your
`pcc-deploy.toml` file.

**--username / -u** `string`

Registry username for authentication. When not specified, automatically parsed
from the `image` field in your `pcc-deploy.toml` file (e.g., `myusername` from
`myusername/app:1.0`).

**--registry-url** `string`

Custom registry URL (required for custom registries). When not specified,
automatically parsed from the `image` field for custom registries (e.g.,
`gcr.io` from `gcr.io/project/app:1.0`).

**Build Configuration:**

**--version / -v** `string`

Version tag for the image. When not specified, automatically extracted from
the `image` field in your `pcc-deploy.toml` file (e.g., `1.0` from
`myusername/app:1.0`).

**--no-push** `boolean` (default: false)

Build and tag only, do not push to registry. Useful for local testing or when
you want to push manually later.

**--no-latest** `boolean` (default: false)

Do not tag the image as `latest`. By default, images are tagged with both the
specified version and `latest`.

**--yes / -y** `boolean` (default: false)

Skip the build confirmation prompt. Required in CI — without it the command
reaches a prompt with no terminal and exits 2.

## Configuration

The `docker build-push` command reads configuration from your `pcc-deploy.toml` file to minimize required command-line arguments. Here's how different registry setups work:

### Docker Hub (Default)

For Docker Hub repositories, the minimal configuration is:

```toml theme={null}
agent_name = "my-agent"
image = "myusername/my-agent:1.0"
```

This automatically configures:

* Registry: `dockerhub`
* Username: `myusername`
* Agent name: `my-agent`
* Version: `1.0`

### Custom Registry

For custom registries like Google Container Registry, AWS ECR, or private registries:

```toml theme={null}
agent_name = "my-agent"
image = "gcr.io/my-project/my-agent:1.0"
```

This automatically configures:

* Registry: `custom`
* Registry URL: `gcr.io`
* Username/Project: `my-project`
* Agent name: `my-agent`
* Version: `1.0`

### Docker Configuration Section

For advanced configuration, add a `[docker]` section:

```toml theme={null}
agent_name = "my-agent"
image = "myusername/my-agent:1.0"

[docker]
auto_latest = false  # Don't tag as 'latest'
```

Available `[docker]` options:

**auto\_latest** `boolean` (default: true)

Whether to automatically tag the image as `latest` in addition to the
specified version.

**registry** `string`

Registry type, `dockerhub` or `custom`. Used when neither `--registry` nor the
`image` field supplies one.

**registry\_username** `string`

Registry username. Used when neither `--username` nor the `image` field
supplies one.

**registry\_url** `string`

Custom registry URL. Used when neither `--registry-url` nor the `image` field
supplies one.

## Examples

### Basic Usage (Recommended)

With a properly configured `pcc-deploy.toml`:

```shell theme={null}
# Build and push using all configuration from pcc-deploy.toml
pipecat cloud docker build-push
```

### Override Version

```shell theme={null}
# Use a different version than what's in pcc-deploy.toml
pipecat cloud docker build-push --version 2.0
```

### Build Only

```shell theme={null}
# Build and tag locally without pushing
pipecat cloud docker build-push --no-push
```

### Different Registry

```shell theme={null}
# Override registry settings for one-time builds
pipecat cloud docker build-push --registry custom --registry-url my-registry.com --username myuser
```

### Skip Latest Tag

```shell theme={null}
# Only tag with the specific version, not 'latest'
pipecat cloud docker build-push --no-latest
```

## Platform Support

`build-push` always builds for `linux/arm64`. This is automatically configured and cannot be changed.

The architecture an agent needs depends on the region it deploys to — Daily-hosted regions run `arm64`, which is what this command produces. To build for a different architecture, build and push the image yourself rather than through this command.

## Error Handling

The command provides helpful error messages for common issues:

* **Authentication errors**: Suggests the appropriate `docker login` command
* **Missing Dockerfile**: Indicates that a Dockerfile must be present in the current directory
* **Registry access issues**: Provides guidance on checking permissions and authentication


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.