> ## 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. # Going live > Create a package, choose a host, and deploy it with the right configuration and credentials. Deploy an Unmute package to LiveKit Cloud, Pipecat Cloud, or SLNG, then update it from the same authored files. Validation checks your declarations; compilation turns them into what the selected target runs. On this page: * [Quickstart](#quickstart) - create, compile, and choose a host * [Keep the package as the source](#1-keep-the-package-as-the-source) - what belongs where * [Choose models and regions](#2-choose-models-and-regions) - configuration and target limits * [Separate accounts and credentials](#3-separate-accounts-and-credentials) - names and values * [Deploy and verify](#4-deploy-and-verify) - follow the hosting route * [Update the agent](#5-update-the-agent) - code, secrets, and names * [Advanced](#advanced) - custom code and hosting limits * [Troubleshooting](#troubleshooting) - symptom, cause, and fix * [Where to go next](#where-to-go-next) ## Quickstart Run these commands from the directory that will hold your new package: ```sh Terminal theme={null} unmute init my-agent cd my-agent unmute validate unmute compile ``` With no saved organization manifest, named initialization creates a LiveKit package. Run `unmute init` without a name for the interactive target choices. A saved manifest guides creation through its allowed choices; see [initialization](/reference/cli/init#1-choose-the-contract). Already have a package? Start inside it at `unmute validate`. To change its target, follow [Switching a package](/targets/overview#switching-a-package-to-another-target), including the model changes that target needs. `--target` selects a declared instance; it does not convert the package to another framework. Then follow **one** hosting guide: | Destination | What you deploy | First deployment | | -------------------------------------- | ------------------------ | ---------------------------------------------- | | [LiveKit Cloud](/deploy/livekit-cloud) | Generated Python project | `lk agent create` from `build/livekit/` | | [Pipecat Cloud](/deploy/pipecat-cloud) | Generated Python project | `pipecat cloud deploy` from `build/pipecat/` | | [SLNG](/deploy/slng) | Compiled agent body | `unmute deploy --target slng` from the package | The target guides supply the authentication, destination, region, and secret steps those commands need. `unmute deploy` currently pushes **SLNG only**. ## 1. Keep the package as the source | Authored file | What you change | | --------------------------------------- | ---------------------------------------------------------------------- | | `agent.yaml` | Agent declarations, model bindings, call behavior, and secret names | | `instructions.md` and task prompt files | What the agent should do and say | | `targets.yaml` | Target instances, supported framework version, and deployment settings | | `tools/.yaml` | Tool inputs and execution choice | | Python files named by `local.handler` | Your tool functions, on LiveKit and Pipecat | | `connections/.yaml` | A supported phone route and its environment names | `unmute validate` checks the package against each selected target. `unmute compile` performs those checks too, then writes `build//`. No provider credentials are needed to compile. On LiveKit and Pipecat, that directory includes a `Dockerfile`, `pyproject.toml`, runtime code, `.env.example`, and `README.md`. Pipecat also gets `pcc-deploy.toml`. SLNG gets an agent body and a runbook, with no Python project or container to build. Read the generated `README.md` for your build's commands and required values. `compile-report.json` records resolved models, dependencies, sizing, environment names, and target limits. Generated files hold names, never credential values. Recompilation replaces the selected build directory. Keep authored code outside `build/`. The compiler preserves `.env`, `livekit*.toml`, and `samples/*.json`; it does not preserve arbitrary edits or added modules. ## 2. Choose models and regions Models live under `models` in `agent.yaml`. Agents bind a named reasoning and voice entry; the package also supplies listening and turn detection where its [pipeline](/build/architecture/overview) uses them. For example, this is the reasoning entry from the current scaffold. Merge it into the existing `models.think` block; it is one supported choice: ```yaml agent.yaml theme={null} models: think: assistant_model: provider: openai model: gpt-5.6-terra params: reasoning_effort: none ``` Selects an integration for this model role and target. See the role pages below. The provider's model identifier. Requiredness and defaults depend on the integration; copy a supported binding from its role page. Provider settings for this binding. Omit to use the integration's defaults. These are not an unrestricted runtime configuration API. | Role | Bindings, credentials, and target support | | ------------------- | ----------------------------------------- | | Reasoning | [Language models](/models/llm) | | Speech recognition | [Speech to text](/models/stt) | | Speech generation | [Text to speech](/models/tts) | | Turn detection | [Turn detection](/models/turn-detection) | | A live speech model | [Live models](/models/live) | Unmute checks provider support and known invalid settings. It transforms some settings and forwards others to the provider integration; the compile report shows the resolved binding. Validation cannot prove a model exists in your account or that every forwarded parameter will succeed. The role pages link to the provider's parameter and credential documentation. For a target-specific choice, use a [model override](/targets/overview#overrides-not-forks). An override replaces the provider, model, and parameters. Omitted shared behavior settings, such as turn timing, carry forward. Keep three different region choices separate: | Setting | What it controls | | -------------------------------------------------- | ------------------------------------------------------------------------------ | | Target `deployment_region` | Where the host runs the agent; allowed values and defaults are target-specific | | Provider inference region or endpoint | Where a model request runs, when that integration supports choosing it | | Provider routing, such as SLNG `params.world_part` | Which provider gateway receives the request | A hosting region does not move a provider's inference service. See [target fields](/targets/overview#targets-yaml) and the [SLNG router](/optimization/context-router) for their respective settings. ## 3. Separate accounts and credentials | Concept | Where it belongs | | ------------------------------ | ------------------------------------------------------------------------------------------------- | | Deployment authentication | Your host CLI login or deployment credential, on the developer machine or CI runner | | Destination account or project | The host CLI's explicit project or organization selection | | Provider credentials | Keys issued by the selected model or service provider | | Runtime secrets | Values provisioned into the deployed agent's environment or SLNG Vault | | Platform-injected values | Connection settings the host supplies, such as LiveKit Cloud's connection URL and key pair | | Application configuration | Non-secret environment values, such as an API base URL, read through a supported field or handler | For a code target, declare environment names separately from provisioning their values. Merge the names your package reads into this list: ```yaml agent.yaml theme={null} secrets: - SERVICE_API_TOKEN - SERVICE_API_URL ``` Inventory of environment names the generated project reads, including non-secret configuration. Declaring a name does not create or populate a host secret. SLNG derives its Vault requirements from the compiled body instead. After compiling, make a deployment file from that target's `.env.example`. Fill only the names read by the deployed agent. Some routes also list values for a separately hosted helper; follow the comments rather than uploading the whole development environment. For a handler that reads these two names, a minimal file has this shape. Replace the placeholders privately before using it: ```dotenv .env.deploy (outside the build directory) theme={null} SERVICE_API_TOKEN=REPLACE_WITH_PROVIDER_ISSUED_VALUE SERVICE_API_URL=https://api.example.com ``` Keep this file out of source control and the uploaded build context. Use a secret manager or a private editor to fill values; do not put them in command arguments, generated code, or image layers. See [Credentials](/build/credentials) for the fields that read environment names. Call [variables](/build/variables) hold conversation data. Prompt interpolation is not a way to deliver credentials. Updating a deployed value also does not create or revoke its provider key; manage that key with its issuing provider. ## 4. Deploy and verify Each hosting guide separates first creation, later code updates, and secrets-only changes. It also explains how the host finds the existing agent: [LiveKit](/deploy/livekit-cloud), [Pipecat](/deploy/pipecat-cloud), [SLNG](/deploy/slng). Check each stage separately: 1. **Validation passes:** the package fits the target. Provider access remains untested. 2. **The build finishes:** the host has an image or agent body. Check readiness next. 3. **The worker is ready:** open a new session through the selected host and transport. 4. **A full interaction works:** speak a short question, confirm the input was received, and hear a relevant answer. 5. **The application works:** exercise a tool or task that matters to your agent, then end the session. A greeting proves output works; it does not prove microphone input or tool credentials work. Use host status and logs from the target guide to locate the failed stage. Keep transcript and credential values out of diagnostic reports. For phone calls, deploy first, then finish the [carrier setup](/telephony/overview). `unmute dev` is the [local browser workflow](/dev/overview), not a deployed phone test. ## 5. Update the agent Change the authored prompt, tool, model, or configuration, then run from the package directory: ```sh Terminal theme={null} unmute validate unmute compile ``` Follow the target's **update** command using the existing deployment identity. Code targets build a new image for changed code or compiled settings. SLNG's `unmute deploy` validates and recompiles automatically before pushing. A changed value under an existing environment name needs the host's secrets-only workflow. Adding a new required name also changes the package's inventory, so compile and deploy that source change. Check a new session after either update. `--target livekit` replaces only `build/livekit/`. Deploying from another build directory can ship stale code, names, or requirements. Compile the instance you intend to deploy. ### Except changing its name The package's `name` joined to its target instance becomes the deployment name. A rename is an identity change, and phone routing may still point at the old one. | Target | What a rename changes | | ------- | --------------------------------------------------------------------------------------------------------------- | | LiveKit | A package rename changes the dispatch name; the same build directory keeps its cloud agent ID in `livekit.toml` | | Pipecat | The manifest names a new agent and secret set; the old agent remains | | SLNG | The push resolves the new name; existing callers still use the old agent ID | Renaming a target also changes its build directory. On LiveKit, recover the existing agent config in that new directory before updating; compilation does not move it from the old folder. Follow the rename steps for [LiveKit](/deploy/livekit-cloud#renaming-the-agent-breaks-that-rule), [Pipecat](/deploy/pipecat-cloud#renaming-the-agent), or [SLNG](/deploy/slng#renaming-the-agent) before changing a production name. ## Advanced ### Add only the code you need Start with native declarations and [tools](/build/tools/overview). Use a webhook for an HTTP service or MCP for a supported remote tool server. Use a [local Python handler](/build/tools/python) for logic inside the generated LiveKit or Pipecat process. [Sharing Python helpers](/build/tools/python#share-a-helper-between-tools) explains the supported single-source-file pattern and the limit on separate imported modules. Arbitrary module trees and data files are not copied into the build. Declared [knowledge documents](/build/tools/knowledge) have their own supported inclusion path. There is no authored lifecycle-hook API or custom Dockerfile hook. LiveKit's [target pins](/targets/overview#targets-yaml) can change versions of recognized dependencies within supported bounds; they cannot add arbitrary packages. Pipecat does not support those overrides. Per-tool dependency declarations are refused on both code targets. Use the compiler-owned build files for the native workflow. An SDK that needs an extra package or a custom startup service has no durable package extension point today; consider a remote tool service instead. ### Hosting the generated container yourself The managed-host pages cover the native deployment commands. Operating the container yourself also means supplying networking, credentials, monitoring, and session draining. A LiveKit worker connects out to LiveKit Server. The server needs public media connectivity and trusted TLS; SIP adds its own signaling and media service. Follow [LiveKit's self-hosting documentation](https://docs.livekit.io/transport/self-hosting/). For self-hosted Pipecat browser calls, the generated SmallWebRTC configuration adds no ICE servers. Cross-network use needs a supported STUN/TURN setup that Unmute does not currently expose as an authored deployment option. ## Troubleshooting | Symptom | Cause | Fix | | ---------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | The host cannot find a project | Deployment ran from the authored package or a partial build | Compile, then use the complete `build//` directory named by the guide | | An imported module or data file is missing | Compilation copies selected handlers, not their import tree or adjacent files | Use the supported shared-handler layout or move the operation to a remote tool | | A worker reports a missing credential | Declaring a name did not provision its value, or it went to another destination | Compare the generated inventory with the selected host's secret names | | A model request rejects a parameter or region | Provider acceptance is not fully checked offline | Read that integration's supported parameters and account availability, then change the binding | | An update creates another agent | The name, destination, or saved identity changed | Check the target's identity and rename steps before deploying again | | The first session fails | The image exists but the worker is still starting | Wait for readiness and read startup logs before testing again | | The greeting plays but the agent hears nothing | The client may have no active microphone input | Check microphone permission, selected device, and mute state; then inspect input events | ## Where to go next Create a cloud agent, update it, and manage its secrets. Deploy the generated project to a chosen organization and region. Push an agent body and resolve its hosted dependencies. Keep reusable tool logic in the authored package.