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:

pipecat cloud docker build-push [ARGS] [OPTIONS]

Arguments:

agent-name · string

Name of the agent to build image for. If not provided, uses the agent_name from your pcc-deploy.toml file.

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:

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:

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:

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.

Examples

Basic Usage (Recommended)

With a properly configured pcc-deploy.toml:

# Build and push using all configuration from pcc-deploy.toml
pipecat cloud docker build-push

Override Version

# Use a different version than what's in pcc-deploy.toml
pipecat cloud docker build-push --version 2.0

Build Only

# Build and tag locally without pushing
pipecat cloud docker build-push --no-push

Different Registry

# Override registry settings for one-time builds
pipecat cloud docker build-push --registry custom --registry-url my-registry.com --username myuser

Skip Latest Tag

# 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