pipecat cloud deploy

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. Use --force to skip this prompt and also force a new deployment even if the configuration hasn’t changed (replacing all running pods). 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:

string

Unique string identifier for the agent deployment. Must not contain spaces. Defaults to agent_name in pcc-deploy.toml; the deploy exits 1 when neither is set.

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:

string

Path to an alternate deploy config file. Defaults to pcc-deploy.toml in the current directory. Can also be set via the PIPECAT_DEPLOY_CONFIG_PATH environment variable, with the flag taking precedence.

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, and must be in the ready state at deploy time.

string

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

string

Name of the secret set to use for the deployment. The secret set must exist in the specified organization and must be in the ready state — deploys that bind a pending or failed set are rejected.

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.

number

Maximum number of allowed agent instances, at least 1. Omitted, the value isn’t sent, so an existing agent keeps its current maximum. The default cap is 50; if you need more agents, please contact us at help@daily.co or via Discord.

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.

number

default:"7200"

Maximum session duration in seconds. When a session reaches this limit, the session is stopped: the bot is cancelled, with no opportunity for it to say goodbye first. Valid range: 60 to 14400 (4 hours). Defaults to 7200 (2 hours) when unset.See Session duration limits for more information.

string

The agent profile to use for resource allocation: a platform profile (agent-1x, agent-2x, agent-3x) or, in a self-hosted region, one your organization defined with agent profiles create. Omitted, the CLI sends no profile, so a new agent gets the platform default, agent-1x.See Agent Profiles for more information.

string

Explicit sizing for agents in self-hosted regions, as cpu=<quantity>,memory=<quantity> (e.g. cpu=2,memory=4Gi). Mutually exclusive with --profile: passing one clears the other from pcc-deploy.toml. Requires pipecatcloud 1.2.0 or later.

string

CPU architecture the agent image requires: amd64 or arm64. Omitted, the region’s default applies. When a region is set by flag or in pcc-deploy.toml, the choice is validated against that region’s supported architectures (see regions list) before anything is uploaded. Must match how the image was built. Requires pipecatcloud 1.2.0 or later.

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. Must be a region of the organization in use.

boolean

default:"false"

Force a new deployment even if the configuration hasn’t changed, replacing all running pods. Useful for picking up updated container images when using mutable tags like latest, or for refreshing modified secret values.

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.

string

Deploy using an existing cloud build ID instead of building a new image. Takes precedence over image. You can find build IDs using pipecat cloud build list.

boolean

default:"false"

Deploy without an image pull secret. Without --yes or --force, an image deploy that names neither --credentials nor an image_credentials in the config file is refused, since a private image would fail to pull. Pass this when the image is public.

string

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

string

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

GitHub source

Create an agent that builds from a GitHub repository instead of an image. The organization must be connected to GitHub first.

string

Repository as owner/repo. Skips the image build and push entirely — Pipecat Cloud builds from the repository.

string

Branch to build and deploy from.

string

default:"Dockerfile"

Path to the Dockerfile within the repository. Distinct from --dockerfile, which applies to cloud builds from a local context.

string

Build context subdirectory within the repository.

--repo only applies when creating an agent. If the agent already exists, the deploy exits 1 and points you at agent link, which re-points an existing agent.

A GitHub source can’t be combined with an image, --build-id, or --resources / [resources]: a deploy is built from a repository or from an image, not both, and a GitHub-sourced agent is sized with --profile. The first deploy is followed through its build, so the command reports whether it succeeded rather than returning as soon as it’s queued.

Examples

Deploy a new agent:

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

Update an existing agent with a new image:

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

Deploy with a specific secret set:

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

Deploy a public image without an image pull secret:

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

Keep one instance always warm to avoid cold starts:

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

Limit the maximum number of agent instances:

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

Deploy to a specific region:

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

Deploy with Krisp VIVA noise cancellation:

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

Cap session duration (useful as a safety net for short-interaction agents):

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

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

Create an agent that builds from a GitHub repository:

pipecat cloud deploy my-agent --repo my-org/my-bot --branch main

Deploy using an alternate config file:

pipecat cloud deploy --config-file pcc-deploy.staging.toml

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. To use an alternate config file (e.g. for different environments), pass --config-file:

pipecat cloud deploy --config-file pcc-deploy.staging.toml

You can also set the PIPECAT_DEPLOY_CONFIG_PATH environment variable, with the --config-file flag taking precedence.

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

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. Maximum 54 characters.

agent_name = "my-voice-agent"

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

string

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

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

string

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

region = "us-east"

string

Name of the secret set to use for environment variables. The secret set must exist in the same region as the agent and must be in the ready state — deploys that bind a pending or failed set are rejected.

secret_set = "my-agent-secrets"

string

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

image_credentials = "dockerhub-credentials"

string

Agent profile for resource allocation. Takes the same values as --profile.

agent_profile = "agent-2x"

string

CPU architecture the agent image requires: amd64 or arm64. Omitted, the region’s default applies. See Pipecat Enterprise Agent Sizing.

architecture = "arm64"

table

Explicit sizing for agents in self-hosted regions, using Kubernetes quantities. Mutually exclusive with agent_profile.

[resources]
cpu = "1"
memory = "2Gi"

number

default:"7200"

max_session_duration = 300

string

default:"none"

Authentication required on the agent’s WebSocket endpoint. none for no authentication, or token to require an HMAC session token from /start. See WebSocket authentication.

websocket_auth = "token"

Scaling Configuration

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

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

number

Maximum number of agent instances allowed, at least 1. Omitted, an existing agent keeps its current maximum.

[scaling]
max_agents = 20

Krisp VIVA Configuration

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

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:

string

default:"."

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

[build]
context_dir = "."

string

default:"Dockerfile"

Path to the Dockerfile within the build context.

[build]
dockerfile = "Dockerfile"

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/"]

GitHub Source Configuration

Build from a repository instead of an image, in a [git] section. Command-line flags take precedence over these values.

string

Repository as owner/repo.

[git]
repo = "my-org/my-bot"

string

Branch to build and deploy from.

[git]
branch = "main"

string

default:"Dockerfile"

Path to the Dockerfile within the repository.

[git]
dockerfile_path = "docker/Dockerfile"

string

Build context subdirectory within the repository.

[git]
subdirectory = "bot"

Like --repo, a [git] section only applies when the agent is created. Once the agent exists, a pipecat cloud deploy with a [git] section exits 1, so remove the section after the first deploy and ship later commits with agent deploy --github.

Complete Example

With cloud build
With custom image
Self-hosted region

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

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

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

# Basic agent configuration
agent_name = "my-voice-agent"
image = "your-dockername/my-voice-agent:0.1"
region = "pce-acme-us-east"
architecture = "arm64"

# Referenced secrets (Kubernetes Secrets in your cluster)
secret_set = "my-agent-secrets"
image_credentials = "my-registry-creds"

# Explicit sizing instead of an agent profile
[resources]
cpu = "1"
memory = "2Gi"

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

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

Get Started

Standards

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

pipecat cloud deploy

Usage

GitHub source

Examples

Configuration File (pcc-deploy.toml)

File Location

Precedence

Configuration Options

Required Fields

Optional Fields

Scaling Configuration

Krisp VIVA Configuration

Cloud Build Configuration

GitHub Source Configuration

Complete Example

Using the Configuration File