> ## Documentation Index
> Fetch the complete documentation index at: https://unmute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unmute compiles to exactly three targets. Pipecat and LiveKit are code targets: compile writes a Python project you run. SLNG is a hosted target: compile writes a deployment body and SLNG runs the agent, so it has no `unmute dev`. Those three are the only values `provider` accepts in `targets.yaml`. Deepgram and ElevenLabs appear in these docs as model vendors, which is not the same thing as a target, and `slng` is both.
> The Go structs in `internal/spec` and `internal/ir` are the schema truth. Check a field against them, or run `unmute validate`, rather than against what you remember.

# Go live on Pipecat Cloud

> Compile your package, choose an organization, deploy it, and update its code or secrets.

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](#quickstart) - the first deployment
* [Prepare the package](#1-prepare-the-package) - target, version, and build files
* [Choose the destination](#2-choose-the-destination) - login, organization, and region
* [Supply runtime values](#3-supply-runtime-values) - a dedicated secret set
* [Deploy and verify](#4-deploy-and-verify) - readiness and a complete interaction
* [Every later deploy](#every-later-deploy) - update the existing agent
* [Secrets-only updates](#secrets-only-updates) - change values without rebuilding
* [Advanced](#advanced) - warm instances, names, and customization
* [Troubleshooting](#troubleshooting) - symptom, cause, and fix
* [Where to go next](#where-to-go-next)

## Quickstart

Start with a package named `my-agent` and a target named `pipecat`.
[Create a package](/deploy/going-live) first if you do not have one.
Install the [Pipecat CLI](https://docs.pipecat.ai/api-reference/cli/overview)
with its cloud commands; this needs Python 3.11 or later and `uv`:

```sh Terminal theme={null}
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/`:

```sh Terminal theme={null}
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.
Read `agent_name`, `secret_set`, and any `region` in the generated
`pcc-deploy.toml`. These examples use the names derived from `my-agent`.

```sh Terminal — from my-agent/build/pipecat theme={null}
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:

```sh Terminal — from my-agent/build/pipecat theme={null}
pipecat cloud deploy
pipecat cloud agent status my-agent-pipecat
```

If the manifest declares a region, pass that same region to `secrets set`.
If it has no `secret_set`, skip creating one.
Finish with the [interaction check](#4-deploy-and-verify).

## 1. Prepare the package

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

```yaml targets.yaml theme={null}
targets:
  pipecat:
    provider: pipecat
    version: "1.10.0"
```

<ParamField path="targets" type="map of target definitions" required>
  Targets the package can compile. The entry name selects `--target` and the build folder.
</ParamField>

<ParamField path="provider" type="string" required>
  Use `pipecat` for this hosting route.
</ParamField>

<ParamField path="version" type="string" required>
  Exact framework version. This release supports `1.10.0`; omitted or unsupported
  versions are refused. The cloud CLI is installed separately from this runtime pin.
</ParamField>

Keep prompts, models, and tools in the authored package. Select models through
[model bindings](/reference/agent-yaml#models), with any target overrides in
[`targets.yaml`](/reference/targets-yaml#models-overrides).
See [Pipecat support](/targets/pipecat) 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` currently pushes SLNG targets only.

| Generated file                | Role                                                                    |
| ----------------------------- | ----------------------------------------------------------------------- |
| `pcc-deploy.toml`             | Deployment name, optional region and secret set, and declared scaling   |
| `Dockerfile`                  | Compiler-owned Cloud build using the Pipecat base image and Python 3.12 |
| `pyproject.toml`              | Exact framework version and generated dependencies                      |
| `bot.py` and supporting files | Runnable agent, local handlers, and declared knowledge files            |
| `.dockerignore`               | Excludes `.env`, `.env.*`, and local Python environments from the build |
| `.env.example`                | Environment names to review and fill                                    |
| `README.md`                   | Package-specific setup, including transport requirements                |
| `compile-report.json`         | Resolved bindings, sizing, and validation details                       |

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](https://docs.pipecat.ai/api-reference/cli/cloud/organizations)
and [account permissions](https://docs.pipecat.ai/pipecat-cloud/fundamentals/accounts-and-organizations).
Use an account permitted to manage agents and secrets in that organization.

### Choose a hosting region

```sh Terminal theme={null}
pipecat cloud regions list
pipecat cloud organizations default-region
```

Omitting `deployment_region` uses the organization's default placement. To
choose explicitly, add it to the existing target and recompile:

```yaml targets.yaml — merge into the existing target theme={null}
targets:
  pipecat:
    deployment_region: eu-central
```

<ParamField path="deployment_region" type="string">
  One Pipecat Cloud worker region. `eu-central` is an example, not a requirement.
  Unmute forwards the name without checking availability; choose from `regions list`.
  Omission uses platform placement. Multiple regions on one Pipecat target are refused.
</ParamField>

The secret set must use the same region. For the example above:

```sh Terminal — from my-agent/build/pipecat theme={null}
pipecat cloud secrets set my-agent-pipecat-secrets --file .env --region eu-central
```

Hosting region places the worker. Provider inference regions and SLNG
`params.world_part` are separate model settings. See
[regional infrastructure](/optimization/regional-infrastructure).

## 3. Supply runtime values

[Declare secret names](/build/credentials) in the package and provision their
values separately. Use the generated `.env.example` and the runbook's required
environment section to prepare a dedicated deployment `.env`.

This example shows placeholders only. Replace the names with those your package
requires, and fill their values privately:

```dotenv .env — example values only theme={null}
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, as identified in the runbook       |
| 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. Other routes have their own requirements
in the generated runbook.

`--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](/models/llm)
link to setup instructions. Prompt [variables](/build/variables) hold call state
and do not supply credentials.

## 4. Deploy and verify

Run `pipecat cloud deploy` inside `my-agent/build/pipecat/`.
The command reads `pcc-deploy.toml` and builds the directory's Dockerfile in
Cloud. It uses `agent_name` to create the resource, or asks to update a matching
resource. See the [deploy reference](https://docs.pipecat.ai/api-reference/cli/cloud/deploy).

Unmute derives `my-agent-pipecat` from the package name and target name.
That identity is regenerated in `pcc-deploy.toml`; the destination organization
lives in your CLI configuration. Pipecat does not write a separate local agent-ID
file for this workflow.

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:

```sh Terminal theme={null}
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](/telephony/overview).

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

```sh Terminal theme={null}
pipecat cloud agent deployments my-agent-pipecat
pipecat cloud agent logs my-agent-pipecat
```

Use the [agent commands](https://docs.pipecat.ai/api-reference/cli/cloud/agent)
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/`:

```sh Terminal theme={null}
unmute validate my-agent --target pipecat
unmute compile my-agent --target pipecat
cd my-agent/build/pipecat
pipecat cloud organizations list
pipecat cloud deploy
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`, saved LiveKit manifests, and JSON tool samples.
Any hand-edited generated Python or manifest settings are 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](https://docs.pipecat.ai/pipecat-cloud/fundamentals/deploy).

To return to a previous image, select its build ID from deployment history and
follow [redeploying a previous build](https://docs.pipecat.ai/pipecat-cloud/guides/cloud-builds#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:

```sh Terminal — from my-agent/build/pipecat theme={null}
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:

```sh Terminal theme={null}
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](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets).

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:

```sh Terminal — from my-agent/build/pipecat theme={null}
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

Merge this into the existing target and compile again:

```yaml targets.yaml theme={null}
targets:
  pipecat:
    warm_instances: 1
```

<ParamField path="warm_instances" type="integer, 0 or more" default="0">
  Instances Pipecat Cloud holds ready. A positive value emits `[scaling] min_agents`
  in the manifest. Omitted or zero emits no minimum; the platform can scale to zero.
  A positive value adds a standing cost. Other targets refuse a positive value.
</ParamField>

A warm instance avoids cold starts. Some phone routes need it to answer within
the carrier's session window; see [Pipecat over Twilio](/telephony/pipecat-twilio#deploy-with-a-warm-instance).

### 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](/telephony/pipecat-twilio) 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](/deploy/going-live#advanced).
Unmute has no general Pipecat build hook or arbitrary dependency declaration.
Editing generated files does not create a supported extension.

For a temporary host setting, Pipecat's deploy flags override the generated
manifest. Keep repeatable overrides in your deployment script outside `build/`.
Use the [deployment reference](https://docs.pipecat.ai/api-reference/cli/cloud/deploy)
for host options and the [target reference](/reference/targets-yaml) 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 runbook and `.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](/deploy/going-live#advanced)       |
| 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 `warm_instances` for that route                                             |

## Where to go next

<Columns cols={2}>
  <Card title="Going live" icon="rocket" href="/deploy/going-live">
    The package lifecycle and supported customization.
  </Card>

  <Card title="Pipecat target" icon="code" href="/targets/pipecat">
    Supported models, transport choices, and target settings.
  </Card>

  <Card title="Credentials" icon="key" href="/build/credentials">
    Declare runtime names separately from their values.
  </Card>

  <Card title="Phone calls" icon="phone" href="/telephony/overview">
    Connect and verify the carrier route your package uses.
  </Card>
</Columns>