Pipecat Cloud Deployments

Deploying an agent

Deploy your agent to Pipecat Cloud with a single command:

pipecat cloud deploy

The CLI builds your image in the cloud from your project’s Dockerfile and deploys it - no container registry setup needed. For more details on how cloud builds work, see the Cloud Builds guide.

Deploying to a specific region

Agents deploy to your organization’s default region, which is us-west by default. You can deploy to a specific region to reduce latency or meet data residency requirements:

pipecat cloud deploy --region us-east

Agent names are globally unique across all regions. For multi-region deployments, deploy uniquely named agents to each target region (e.g., my-agent-us-west, my-agent-us-east).

Once the deployment completes, you will be able to run your agent on-demand. For a complete list of deployment configuration options, see the CLI deploy reference.

Deploying with a custom image

If you prefer to build and push images to your own container registry, you can specify an image directly:

pipecat cloud deploy my-agent my-image:0.1

Using a private container registry? See our Container Registry guides for setup instructions for GCP Artifact Registry, AWS ECR, and other private registries.

You will be asked to confirm your deployment configuration before proceeding.

Deployment status

Once complete, Pipecat Cloud will return the status of your deployment or any errors that occurred during the deployment process.

Using pcc-deploy.toml

To support shareable deployment configurations, you can create a pcc-deploy.toml file in the root of your project (adjacent to where you run your CLI commands.) The CLI will automatically detect this file and use it to populate the deployment configuration. Any CLI arguments you provide will override the values in the pcc-deploy.toml file. An example pcc-deploy.toml file might look like this:

agent_name = "my-agent"
secret_set = "my-agent-secrets"
agent_profile = "agent-1x"
region = "us-west"

[scaling]
    min_agents = 1

You can optionally enable WebSocket authentication by adding websocket_auth = "token" to require HMAC token authentication on the generic WebSocket endpoint. Defaults to "none" (no authentication required). See the WebSocket Authentication guide for details. If you’re deploying with a custom image, add the image field (and image_credentials for private registries):

agent_name = "my-agent"
image = "your-docker-repository/my-agent:0.1"
image_credentials = "dockerhub-access"
secret_set = "my-agent-secrets"

For a complete reference of all configuration options, see the deploy command documentation.

Agent Profiles

Agent profiles determine the CPU and memory resources allocated to your deployed agents. Choose the profile that best matches your agent’s requirements:

agent-1x (default): 0.5 vCPU and 1 GB of memory. Best for voice agents.
agent-2x: 1 vCPU and 2 GB of memory. Well suited for voice and video agents or voice agents requiring extra processing.
agent-3x: 1.5 vCPU and 3 GB of memory. Best for voice and video agents requiring extra processing or multiple video inputs.

You can specify the agent profile in your deployment: Via CLI:

pipecat cloud deploy --profile agent-2x

Via pcc-deploy.toml:

agent_profile = "agent-2x"

Agent profiles affect resource allocation and impact your usage costs. Choose the smallest profile that meets your agent’s performance requirements.

Checking status of a deployment

You can check the status of a deployment using the CLI:

pipecat cloud agent status my-first-agent

If a deployment was successful and ready to be started, you should see a ready status.

Modifying a deployment

Agents are referenced as a mutable manifest in Pipecat Cloud. Pushing a new image or configuration to the same agent name will update your agent manifest and be used for any new requests.

pipecat cloud deploy --min-agents 2

This command will update the deployment to set the minimum number of instances to 2. To avoid interruption of any active sessions, any running agent instances will continue on the old image until the session concludes. Once those sessions end, the instances running the old image are discarded and will not be returned to the pool.

When there is no new deployment, instances are returned to the pool after a session ends and remain available to serve new sessions during a cooldown period. A new deployment changes this behavior: instances running the prior image are terminated once their sessions conclude, rather than being recycled.

Idle agent instances in your agent pool will be replaced with the new configuration according to the Pipecat Cloud auto-scaling strategy. New agent requests may, therefore, start with prior deployment configuration if updates are not fully propagated. This ensures on-demand availability remains consistent and avoids potential cold starts.

When a deploy does not replace running agents

A deploy only replaces your running agent instances when it creates a new version of your agent. If the configuration you send matches what the agent already has, Pipecat Cloud keeps the current version and leaves your instances alone, so a routine deploy can’t cut off a session that is already in progress. Watch for this if you keep warm instances (min-agents set to 1 or higher): they can keep serving your old code, your deploy will report success, and the output won’t look wrong. These changes do not create a new version:

Scaling only. min-agents and max-agents apply to the running pool in place.
An image tag you already deployed. Pipecat Cloud stores the tag you gave it, not the image behind it, so pushing new content to a tag like :latest and deploying that same tag looks like no change. Cloud builds behave the same way when your project files haven’t changed, because the tag comes from your file contents.
A secret’s value. Your deployment records which secret sets it uses, not the values inside them.

To pick up any of these, force a new version:

pipecat cloud deploy --force

Pinning your base image to an exact version instead of :latest avoids the second case entirely. See Agent images for the available tags, and the --force flag in the CLI reference.

Failed deployments

If a deployment fails (i.e. fails to enter a ready state), requests will be routed to any prior deployments in a ready state. This ensures that your agent remains available to end-users even when a deployment fails.

Delete a deployment

This action is irreversible and will remove all data related to the agent from Pipecat Cloud.

If you no longer need a deployment, you can delete it using the delete command:

pipecat cloud agent delete my-first-agent

Any running agent instances will continue to run until they conclude or are stopped.

Get Started

Fundamentals

Guides

Security & Compliance

Pipecat Cloud Deployments

Deploying an agent

Deploying to a specific region

Deploying with a custom image

Deployment status

Using pcc-deploy.toml

Agent Profiles

Checking status of a deployment

Modifying a deployment

When a deploy does not replace running agents

Failed deployments

Delete a deployment

​Deploying an agent

​Deploying to a specific region

​Deploying with a custom image

​Deployment status

​Using pcc-deploy.toml

​Agent Profiles

​Checking status of a deployment

​Modifying a deployment

​When a deploy does not replace running agents

​Failed deployments

​Delete a deployment

Deploying an agent

Deploying to a specific region

Deploying with a custom image

Deployment status

Using pcc-deploy.toml

Agent Profiles

Checking status of a deployment

Modifying a deployment

When a deploy does not replace running agents

Failed deployments

Delete a deployment