Skip to main content
Once you’ve built an agent image, it’s time to deploy it to Pipecat Cloud.

​
Deploying an agent

Deploying agents to Pipecat Cloud requires first building and pushing your image to a container registry, such as Docker Hub. Use the Pipecat CLI to build and push your Docker image: 
pipecat cloud docker build-push
This command reads your pcc-deploy.toml configuration to automatically build, tag, and push your image to the configured registry. Once your agent image is pushed, deploy it to Pipecat Cloud: 
pipecat cloud deploy
This command will instruct Pipecat Cloud to create a new deployment from your image. Once it has completed, you will be able to run your agent on-demand.
When using pcc-deploy.toml, the CLI automatically reads your configuration. You can also specify arguments directly: pipecat cloud deploy my-agent my-image:0.1
For a complete list of deployment configuration options, see the CLI deploy reference.
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-first-agent"
image = "your-docker-repository/my-first-agent:0.1"
image_credentials = "dockerhub-access"
secret_set = "my-agent-secrets"
agent_profile = "agent-1x"

[scaling]
    min_agents = 1
You can verify your configuration by running pipecat cloud --config.

​
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.
You can specify the agent profile in your deployment: Via CLI: 
pipecat cloud deploy my-agent my-image:latest --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 my-first-agent your-docker-repository/my-first-agent:latest --min-agents 2
This command will update the my-first-agent deployment to use the new image and 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. 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.

​
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.
⌘I