deploy - Pipecat

The deploy command creates a new agent deployment or updates an existing one. It builds a deployment manifest with the provided parameters and monitors the deployment status until the agent is ready. When no image is specified, the CLI will offer to build your agent using Pipecat Cloud Build. This handles building and deploying without requiring you to manage a container registry. A Dockerfile must be present in your build context directory. If the agent name already exists, you’ll be prompted to confirm the update unless the --force flag is used. This command will wait for the active deployment / revision to enter a ready state before returning. If the deployment fails, the command will exit with an error with more information.

Usage

pipecat cloud deploy [ARGS] [OPTIONS]

Arguments:

agent-name

string

required

Unique string identifier for the agent deployment. Must not contain spaces.

image

string

URL of the Docker image to deploy. Must be a valid Docker image URL. For example: docker.io/my-repo/my-image:latest. Not required when using cloud builds or --build-id.

Options:

--credentials / -c

string

Name of the image pull secret to use for accessing private repositories. The secret must be previously created using the pipecat cloud secrets image-pull-secret command.

--organization / -o

string

Organization to deploy the agent to. If not provided, uses the current organization from your configuration.

--secrets / -s

string

Name of the secret set to use for the deployment. The secret set must exist in the specified organization.

--min-agents / -min

number

default:"0"

Minimum number of agent instances to keep warm at all times. Default is 0, which means the agent will scale down to zero when not in use. Setting this to 1 or higher avoids cold starts.

--max-agents / -max

number

default:"50"

Maximum number of allowed agent instances. Must be between 1 and 50. If you need more agents, please contact us at help@daily.co or via Discord.

--krisp-viva-audio-filter

string

Enable Krisp VIVA noise cancellation with the specified audio filter model. Valid values are:

tel: Telephony model (up to 16kHz)
pro: WebRTC model (up to 32kHz)

In addition to this flag, you also need to enable the KrispVivaFilter() for your transport. See the Krisp VIVA documentation for more information.

--enable-managed-keys

boolean

default:"false"

Enable managed API keys for this deployed agent.

--profile / -p

string

default:"agent-1x"

The agent profile to use for resource allocation. Valid values are: agent-1x, agent-2x, agent-3x.See Agent Profiles for more information.

--region / -r

string

Region where the agent will be deployed. If not specified, uses your organization’s default region (typically us-west). Choose a region close to your users for optimal latency.

--force / -f

boolean

default:"false"

Force deployment and skip confirmation prompts. Use with caution.

--yes / -y

boolean

default:"false"

Skip all confirmation prompts, including cloud build prompts. Useful for CI/CD pipelines. When used without an image, automatically triggers a cloud build.

--build-id / -b

string

Deploy using an existing cloud build ID instead of building a new image. Cannot be used together with --image. You can find build IDs using pipecat cloud build list.

--build-dir / -d

string

Build context directory for cloud builds. Defaults to the current directory.

--dockerfile

string

Path to Dockerfile for cloud builds. Defaults to Dockerfile in the build context directory.

Examples

Deploy a new agent:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1

Update an existing agent with a new image:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.2

Deploy with a specific secret set:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --secrets my-secret-set

Deploy a private image using image pull credentials:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --credentials dockerhub-creds

Keep one instance always warm to avoid cold starts:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --min-agents 1

Limit the maximum number of agent instances:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --max-agents 5

Deploy to a specific region:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --region eu-central

Deploy with Krisp VIVA noise cancellation:

pipecat cloud deploy my-first-agent your-docker-repository/my-first-agent:0.1 --krisp-viva-audio-filter tel

Deploy using cloud build (interactive):

pipecat cloud deploy

Deploy using cloud build in CI/CD (no prompts):

pipecat cloud deploy --yes

Deploy using an existing build:

pipecat cloud deploy --build-id abc12345-6789-0abc-def0-123456789abc

Configuration File (pcc-deploy.toml)

The deploy command supports a configuration file for repeatable deployments. Create a pcc-deploy.toml file in your project root to define deployment settings that can be shared across your team and version controlled.

File Location

Place pcc-deploy.toml in the same directory where you run the pipecat cloud deploy command. The CLI will automatically detect and use this file.

Precedence

Values are applied with the following order of precedence:

CLI arguments (highest priority)
pcc-deploy.toml values
Default values (lowest priority)

This allows you to define defaults in the config file while still overriding specific values via CLI flags when needed.

Configuration Options

Required Fields

agent_name

string

required

Name of the agent to deploy. Must start with a lowercase letter or number, can include hyphens, and must end with a lowercase letter or number.

agent_name = "my-voice-agent"

image

string

Docker image URL with tag. Required when not using cloud builds or build_id.

image = "your-dockername/my-agent:0.1"

You must specify either image or build_id, or omit both to trigger a cloud build at deploy time.

Optional Fields

build_id

string

An existing cloud build ID to deploy. Cannot be used together with image.

build_id = "abc12345-6789-0abc-def0-123456789abc"

region

string

Region where the agent will be deployed. If not specified, uses your organization’s default region (typically us-west).

region = "us-east"

secret_set

string

Name of the secret set to use for environment variables. The secret set must exist in the same region as the agent.

secret_set = "my-agent-secrets"

image_credentials

string

Name of the image pull secret for private registries. The image pull secret must exist in the same region as the agent.

image_credentials = "dockerhub-credentials"

agent_profile

string

default:"agent-1x"

Agent profile for resource allocation. Valid values: agent-1x, agent-2x, agent-3x.

agent_profile = "agent-2x"

enable_krisp

boolean

default:"false"

Deprecated: Enable legacy Krisp noise cancellation. Use krisp_viva instead.

enable_krisp = false

enable_managed_keys

boolean

default:"false"

Enable managed API keys for this deployment.

enable_managed_keys = false

Scaling Configuration

Define auto-scaling behavior in a [scaling] section:

scaling.min_agents

number

default:"0"

Minimum number of agent instances to keep warm. Setting to 0 allows scaling to zero but may result in cold starts.

[scaling]
min_agents = 1

scaling.max_agents

number

default:"50"

Maximum number of agent instances allowed.

[scaling]
max_agents = 20

Krisp VIVA Configuration

Configure Krisp VIVA noise cancellation in a [krisp_viva] section:

krisp_viva.audio_filter

string

Krisp VIVA audio filter model. Valid values: tel (telephony, up to 16kHz) or pro (WebRTC, up to 32kHz). Omit or set to null to disable.

[krisp_viva]
audio_filter = "tel"

Cloud Build Configuration

Configure cloud build behavior in a [build] section:

build.context_dir

string

default:"."

Directory to use as the build context. Defaults to the current directory.

[build]
context_dir = "."

build.dockerfile

string

default:"Dockerfile"

Path to the Dockerfile within the build context.

[build]
dockerfile = "Dockerfile"

build.exclude.patterns

string[]

Additional file patterns to exclude from the build context. Common patterns like .git, .env, __pycache__, and .venv are excluded automatically.

[build.exclude]
patterns = ["*.md", "tests/", "docs/"]

Complete Example

With cloud build
With custom image

# Basic agent configuration
agent_name = "my-voice-agent"
region = "us-west"

# Secrets
secret_set = "my-agent-secrets"

# Resource allocation
agent_profile = "agent-1x"

# Auto-scaling configuration
[scaling]
min_agents = 1
max_agents = 20

# Cloud build configuration (optional, shown with defaults)
[build]
context_dir = "."
dockerfile = "Dockerfile"

[build.exclude]
patterns = ["*.md", "tests/"]

# Basic agent configuration
agent_name = "my-voice-agent"
image = "your-dockername/my-voice-agent:0.1"
region = "us-west"

# Secrets and credentials
secret_set = "my-agent-secrets"
image_credentials = "dockerhub-credentials"

# Resource allocation
agent_profile = "agent-1x"

# Features
enable_managed_keys = false

# Auto-scaling configuration
[scaling]
min_agents = 1
max_agents = 20

# Krisp VIVA noise cancellation
[krisp_viva]
audio_filter = "tel"

Using the Configuration File

Once you have a pcc-deploy.toml file, simply run:

pipecat cloud deploy

The CLI will automatically load your configuration. You can still override any value using CLI flags:

# Use config file but override the region
pipecat cloud deploy --region eu-central

# Use config file but force update without confirmation
pipecat cloud deploy --force

Commands

​Usage

​Examples

​Configuration File (pcc-deploy.toml)

​File Location

​Precedence

​Configuration Options

​Required Fields

​Optional Fields

​Scaling Configuration

​Krisp VIVA Configuration

​Cloud Build Configuration

​Complete Example

​Using the Configuration File

Usage

Examples

Configuration File (pcc-deploy.toml)

File Location

Precedence

Configuration Options

Required Fields

Optional Fields

Scaling Configuration

Krisp VIVA Configuration

Cloud Build Configuration

Complete Example

Using the Configuration File