Go live on Pipecat Cloud

Deploy your Unmute package as a managed Pipecat Cloud agent. Unmute writes the runnable project; Pipecat Cloud builds and hosts it. Change the authored package, then compile again before deploying code changes. On this page:

Quickstart - the first deployment
Prepare the package - target, version, and build files
Choose the destination - login, organization, and region
Supply runtime values - a dedicated secret set
Deploy and verify - readiness and a complete interaction
Every later deploy - update the existing agent
Secrets-only updates - change values without rebuilding
Advanced - warm instances, names, and customization
Troubleshooting - symptom, cause, and fix
Where to go next

Quickstart

Start with a package named my-agent and a target named pipecat. Create a package first if you do not have one. Install the Pipecat CLI with its cloud commands; this needs Python 3.11 or later and uv:

Terminal

uv tool install "pipecat-ai[cli]" --with pipecatcloud
pipecat cloud auth login
pipecat cloud organizations select
pipecat cloud organizations list

Run these from the directory containing my-agent/:

Terminal

unmute validate my-agent --target pipecat
unmute compile my-agent --target pipecat
cd my-agent/build/pipecat
cp .env.example .env

Fill .env with only the deployed agent’s required values, as described below. Unmute does not write a pcc-deploy.toml yet. You pass the agent name, secret set and region to pipecat cloud deploy as flags. These examples use my-agent-pipecat and my-agent-pipecat-secrets. Pick your own names.

Terminal — from my-agent/build/pipecat

pipecat cloud secrets set my-agent-pipecat-secrets --file .env
pipecat cloud secrets list my-agent-pipecat-secrets

Wait until the set reports ready, then deploy:

Terminal — from my-agent/build/pipecat

pipecat cloud deploy my-agent-pipecat --secrets my-agent-pipecat-secrets
pipecat cloud agent status my-agent-pipecat

If you deploy to a region, pass the same --region to secrets set and to deploy. Finish with the interaction check.

1. Prepare the package

Merge this target into an existing package’s targets.yaml:

targets.yaml

targets:
  pipecat:
    provider: pipecat
    version: "1.12.0"

map of target definitions

required

Targets the package can compile. The entry name selects --target and the build folder.

string

required

Use pipecat for this hosting route.

string

required

Exact framework version. This release supports 1.12.0; omitted or unsupported versions are refused. The cloud CLI is installed separately from this runtime pin.

Keep prompts, models, and tools in the authored package. Select models through model bindings, with any target overrides in targets.yaml. See Pipecat support for model and transport limits. compile validates the selected target before writing my-agent/build/pipecat/. It needs no hosting login. Validation checks the package and known capabilities; it does not make a successful provider request. unmute deploy publishes SLNG agents or connects Twilio numbers. Pipecat uses its own deployment command.

Generated file	Role
`Dockerfile`	Compiler-owned Cloud build using Python 3.12
`pyproject.toml`	Exact framework version, `unmute-core`, and generated dependencies
`bot.py`, `agent.json`, `spec.py`, `speech.py`	The entry point and the agent the `unmute-core` library runs
`state.py`, `tools/`, `knowledge/`	Your state, local handlers, and declared knowledge files, copied
`.dockerignore`	Excludes `.env`, `.env.*`, and local Python environments from the build
`.env.example`	Environment names to review and fill
`compile-report.json`	The target, runtime, and required environment names

Keep the generated directory together as the build context. No custom Dockerfile, container registry, or local Docker build is required for this path.

2. Choose the destination

Login authenticates the deployment operator. The selected organization decides where commands act; it is separate from model-provider accounts. organizations select saves that choice in the CLI’s local configuration. Run organizations list before each deployment to confirm it. For scripts, use --organization on deployment and secret commands with the organization identifier from the listing. See the organization commands and account permissions. Use an account permitted to manage agents and secrets in that organization.

Choose a hosting region

Terminal

pipecat cloud regions list
pipecat cloud organizations default-region

Omitting a region uses the organization’s default placement. To choose one, pass --region to deploy. Unmute writes no manifest, so deployment_region reaches nothing and the flag is the way to choose a region. eu-central is an example. Choose from regions list. The secret set must use the same region:

Terminal — from my-agent/build/pipecat

pipecat cloud secrets set my-agent-pipecat-secrets --file .env --region eu-central
pipecat cloud deploy my-agent-pipecat --secrets my-agent-pipecat-secrets --region eu-central

Hosting region places the worker. Provider inference regions and SLNG params.world_part are separate model settings. See regional infrastructure.

3. Supply runtime values

Declare secret names in the package and provision their values separately. Use the generated .env.example to prepare a dedicated deployment .env. This example shows placeholders only. Replace the names with those your package requires, and fill their values privately:

.env — example values only

MODEL_API_KEY=replace-with-provider-key
SERVICE_API_TOKEN=replace-with-service-token
SERVICE_API_URL=https://api.example.com

Kind of value	Where it belongs
CLI login or deployment token	The operator’s CLI configuration or deployment environment
Required provider and tool credentials	The deployed agent’s secret set
Runtime application URLs and other environment settings	The same set, under the names the package reads
Helper-only phone settings	The separately hosted helper
Platform session connection details	Supplied by the selected Cloud transport when the session starts

Do not upload the operator’s unrelated development credentials. On a daily-sip route, remove helper-only entries from the file uploaded to the agent. Keep entries marked as shared. See the phone guide for each route’s requirements. --file sends every entry in the file. The generated Dockerfile reads no secret values, and .dockerignore excludes .env. Keep the value file out of source control. Unmute preserves this .env when it recompiles, but rewrites .env.example with the current requirements. Provider keys come from the chosen provider; the model pages link to setup instructions. Prompt variables hold call state and do not supply credentials.

4. Deploy and verify

Run pipecat cloud deploy my-agent-pipecat --secrets my-agent-pipecat-secrets inside my-agent/build/pipecat/. The command builds the directory’s Dockerfile in Cloud. It creates the agent with that name, or asks to update a matching one. See the deploy reference. The agent name is yours to choose. Use the same name on every deploy. The destination organization lives in your CLI configuration. Check the deployment, then open a session through the transport your package uses. For a browser session supported by the generated project, select a Cloud public API key and start a Daily session:

Terminal

pipecat cloud organizations keys use
pipecat cloud agent start my-agent-pipecat --use-daily

Create a key through organizations keys create if none exists. This public session key is separate from the deployment login and your model-provider keys. Use the returned session connection details in your supported client. Phone routes need their own carrier setup and test.

Check	What it establishes
Build succeeded	The generated project became an image
Agent status is ready	The platform can serve sessions
Latest deployment names the expected build	The intended compiled image is selected
Speak a short request and receive a relevant reply	Input, model request, and output all worked

A greeting alone does not prove input works. Allow microphone access and unmute the client before speaking. Then exercise one tool if the package uses tools. This is deployment smoke acceptance; application-specific end-to-end tests come next.

Terminal

pipecat cloud agent deployments my-agent-pipecat
pipecat cloud agent logs my-agent-pipecat

Use the agent commands to select a session or deployment in logs. Leave the log level unset to see errors as well as normal messages. Avoid sharing logs that contain caller data or secrets.

Every later deploy

Edit the authored prompts, tools, supported local handlers, or model settings. From the directory containing my-agent/:

Terminal

unmute validate my-agent --target pipecat
unmute compile my-agent --target pipecat
cd my-agent/build/pipecat
pipecat cloud organizations list
pipecat cloud deploy my-agent-pipecat --secrets my-agent-pipecat-secrets
pipecat cloud agent status my-agent-pipecat

Check the regenerated .env.example before deploying. A new provider, renamed setting, or new tool may need another runtime value. Update the set only when its values change; an unchanged code deployment uses its existing values and needs no local secrets file. Keep the same organization, agent name, and secret set to update the intended resource. Cloud builds can reuse an identical build. Compare the selected build with your intended version, then repeat the interaction check. Compilation replaces the generated directory except .env. Any hand-edited generated Python is replaced. Normal updates let active sessions finish on their existing image. New sessions move to the new deployment as it rolls out. A failed deployment can leave the previous ready version serving requests. See deployment behavior. To return to a previous image, select its build ID from deployment history and follow redeploying a previous build. This does not restore earlier secret values or authored files.

Secrets-only updates

Changing the value of an existing runtime name requires no compile or new image. Run these commands in the generated directory, using the existing set and region:

Terminal — from my-agent/build/pipecat

pipecat cloud secrets set my-agent-pipecat-secrets --file .env
pipecat cloud secrets list my-agent-pipecat-secrets

set adds new names and replaces supplied values; names omitted from the file remain in the set. Removing a line from .env therefore does not remove a deployed secret. Remove an obsolete name explicitly:

Terminal

pipecat cloud secrets unset my-agent-pipecat-secrets OLD_API_KEY

The listing shows names and readiness, without values. Wait for ready after changes. Updating the set does not refresh running agents. Each deployment using it needs a forced rollout, as described in Pipecat secret management. Read the current image’s build ID from deployment history. Replace the placeholder below with that ID to roll out the same image without rebuilding:

Terminal — from my-agent/build/pipecat

pipecat cloud agent deployments my-agent-pipecat
pipecat cloud deploy --build-id <current-build-id> --force
pipecat cloud agent status my-agent-pipecat

--force replaces running instances and can interrupt active sessions. Verify a fresh interaction with the new value. Updating a stored value does not create or revoke its provider key. Do that with the provider’s key management. If the code must start reading a new name, also change the package and recompile.

Advanced

Keep an instance ready

Pass --min-agents to deploy:

Terminal — from my-agent/build/pipecat

pipecat cloud deploy my-agent-pipecat --secrets my-agent-pipecat-secrets --min-agents 1

Unmute writes no manifest, so warm_instances in targets.yaml reaches nothing yet. Use the flag. A positive value adds a standing cost. Zero lets the platform scale to zero. A warm instance avoids cold starts. Some phone routes need it to answer within the carrier’s session window; see Pipecat over Twilio.

Renaming the agent

Changing the package or target name creates another deployment; it does not move the existing one. A second hosting region also needs a distinct agent name and a secret set in that region. Compile the new target, provision its set, deploy, and verify an interaction. Then point clients and carrier routes at the new name before retiring the old agent. For cloud-websocket, update the service host in carrier markup; for daily-sip, redeploy the helper with its new AGENT_NAME. See the phone guide for route-specific steps.

Customize supported code

Use native model settings and tools first. Local handlers compile into the project; shared Python modules and dependency limits are covered in Going live. Unmute has no general Pipecat build hook or arbitrary dependency declaration. Editing generated files does not create a supported extension. Pipecat’s deploy flags carry the host settings. Keep them in a deployment script outside build/, so every deploy uses the same ones. Use the deployment reference for host options and the target reference for settings Unmute owns.

Troubleshooting

Symptom	Cause	Fix
Deploy asks for an agent name or cannot find a Dockerfile	Wrong working directory or incomplete build	Compile, then deploy inside `my-agent/build/pipecat/`
Secret set is missing or not ready	Wrong organization/region, or provisioning is pending	Confirm the destination and matching region; wait for the set to report `ready`
Deploy reports ready but behavior stays old	Old compiled files, cached image, or client points elsewhere	Check the selected build and agent name; compile the changed package and redeploy
New secret value has no effect	Existing instances still hold their environment	Force a rollout of the current build after the set is ready
Session fails with a missing environment name	`.env` did not follow a package change	Compare with the current `.env.example`, then update the set and roll out
Import or data-file lookup fails	The module, dependency, or file was never packaged	Use the supported local-code layout and check the customization limits
Provider rejects a parameter or region	Provider availability differs from package validation	Check that model’s provider reference, credentials, and inference region; fix the binding and compile again
Another agent appears after a deploy	Organization, package name, or target name changed	Restore the intended destination and identity; inspect both resources before retiring either
Agent speaks but never hears you	Client microphone is muted or blocked	Enable the microphone and check the selected transport’s input path
First session times out after an idle period	Worker is still starting	Wait for readiness and consider `--min-agents 1` for that route

Where to go next

Going live

The package lifecycle and supported customization.

Pipecat target

Supported models, transport choices, and target settings.

Credentials

Declare runtime names separately from their values.

Phone calls

Connect and verify the carrier route your package uses.

Get started

Build the agent

Best practices

Run and observe

Optimization

Deploy

Phone calls

Targets and models

Configuration files

CLI

Community

Releases

Go live on Pipecat Cloud

Quickstart

1. Prepare the package

2. Choose the destination

Choose a hosting region

3. Supply runtime values

4. Deploy and verify

Every later deploy

Secrets-only updates

Advanced

Keep an instance ready

Renaming the agent

Customize supported code

Troubleshooting

Where to go next

Going live

Pipecat target

Credentials

Phone calls

​Quickstart

​1. Prepare the package

​2. Choose the destination

​Choose a hosting region

​3. Supply runtime values

​4. Deploy and verify

​Every later deploy

​Secrets-only updates

​Advanced

​Keep an instance ready

​Renaming the agent

​Customize supported code

​Troubleshooting

​Where to go next

Going live

Pipecat target

Credentials

Phone calls

Quickstart

1. Prepare the package

2. Choose the destination

Choose a hosting region

3. Supply runtime values

4. Deploy and verify

Every later deploy

Secrets-only updates

Advanced

Keep an instance ready

Renaming the agent

Customize supported code

Troubleshooting

Where to go next