Deploy to Pipecat Cloud
Start here to create a deployment, choose its destination, supply credentials,
and update its code or secrets.
state.py is present when the package has a State class. Unmute does not
write a Pipecat Cloud deploy manifest yet. See Deploy to Pipecat
Cloud.
Target fields
Write these insidetargets.<name> in targets.yaml. The name is your target
instance name, used by --target and the build/<name>/ output folder.
string
required
Use
pipecat for this target. Omission is refused.string
required
An exact
x.y.z framework version from the
supported window.
Omission and unsupported versions are refused; there is no automatic upgrade.string
Accepts
python. If omitted, the generated project still uses Python.string
Required for telephony: the stem of a file under
connections/, using
cloud-websocket or daily-sip with a supported carrier.
See connection fields.
Omit for a browser-only package; a connection without phone use is refused.string or list of strings
One non-empty platform region name, as a string or a one-item list. More than one region is refused.
Unmute forwards region names as written and does not check them against the
platform’s region list. If omitted, no region is passed and platform placement
applies. The generated manifest and secret-set instructions use the same region.
See deployment regions.
map of model definitions
Overrides keyed by existing model names from
agent.yaml, using the
model fields. Omit to use the package’s models.
An override replaces the entry, except that omitted pace, endpointing_delay,
semantic_endpointing, and prompt_suffix carry forward. An override cannot
author pace or a different prompt_suffix.map of strings
This field is accepted but Pipecat does not read it. Omit it; the framework version and model catalog determine the generated dependencies.
integer
A non-negative count of instances to keep ready. A positive value becomes min_agents in the deploy manifest. Omitted or zero emits no minimum, so the platform can scale to zero.
The modules
The project imports theunmute-core library from PyPI
(unmute-core[pipecat]). The library holds the call logic: state, tasks, tools,
telemetry and the model call. The files here only wire it to Pipecat.
bot.py is the entry point. It builds the pipeline and runs one call.
spec.py reads agent.json and builds the objects the library runs: the
tools, each agent’s tasks, the prefetch and the greeting. It checks every name
and path at import, so a broken package fails at start and never during a call.
speech.py holds the speech and model bindings. state.py is your own State
class, copied as you wrote it, and present when the package has one.
Prompts live in agent.json. Edit agent.yaml and compile again rather than
these files.
The generated startup check names missing required environment variables.
See the build’s .env.example and credentials reference.
Your architecture determines whether the pipeline
uses separate speech services or a model that handles audio directly.
Run it without Unmute
uv installs the pinned dependencies on the first run.
Dependencies are pinned
The generatedpyproject.toml follows the providers, turn detector, and tracing
settings your package uses. The framework version comes from your target’s
version: field. Change the package and compile again to update dependencies.
Deploy
Follow Deploy to Pipecat Cloud for the complete sequence: package preparation, destination selection, runtime values, first deployment, updates, and a test interaction. The guide also covers secrets-only changes. Use the generatedbuild/pipecat/ directory as the build context. Keep secret
values out of the image. Supply the runtime values listed by its .env.example
and runbook through the platform’s secret store.
The deployed agent’s name
A package namedmy-agent with target pipecat deploys as my-agent-pipecat.
This is the package’s name: joined to its target,
and it is the agent name you give pipecat cloud deploy. Use the same name for the secret set.
A rename creates another agent and leaves the old one running. Follow
Renaming the agent to move traffic
and remove the old deployment.
Where to go next
The LiveKit project
The same agent, the other runtime.
Going live
What to do with the project you were handed.