Deployments

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 pushing your built image to a container registry, such as Docker Hub.

docker tag my-first-agent your-docker-repository/my-first-agent:0.1
docker push your-docker-repository/my-first-agent:0.1

Once your agent image is pushed, you can deploy it to Pipecat Cloud using the CLI deployment command:

pcc deploy my-first-agent your-docker-repository/my-first-agent:0.1

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.

The deploy command requires both of the following arguments:

• agent-name: The name of the agent to deploy.
• image: The repository and tag of the image to deploy.

For a list of deployment configuration options, please see the CLI reference.

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"
image = "myagentimage:latest"
image_credentials = "dockerhub"
secret_set = "my-secrets"

[scaling]
    min_instances = 0

​

Checking status of a deployment

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

pcc 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.

pcc deploy my-first-agent new-image:latest --min-instances 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 instances will continue on the old image until the session concludes.

Idle 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

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

pcc agent delete my-first-agent

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