deploy

Create or modify an agent deployment

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.

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 · required

URL of the Docker image to deploy. Must be a valid Docker image URL. For example: docker.io/my-repo/my-image:latest.

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 [e-mail] or via Discord.

--enable-krisp / -krisp · boolean · default: "false"

Enable Krisp noise cancellation for this deployed agent. In addition, you also need to enable the KrispFilter() for your transport. See the Krisp Noise Cancellation guide 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 · default: "us-west"

Region where the agent will be deployed. If not specified, defaults to 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.

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

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:

1. CLI arguments (highest priority)
2. pcc-deploy.toml values
3. 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 · required

Docker image URL with tag.

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

Optional Fields

region · string · default: "us-west"

Region where the agent will be deployed. Defaults to us-west if not specified.

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"

Complete Example

# 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