> ## 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 LiveKit Cloud > Create a LiveKit Cloud agent from your package, then update its code and runtime secrets. Deploy your compiled package to a LiveKit Cloud project, then update the same agent. Unmute writes the runnable project; LiveKit's `lk` CLI builds and hosts it. Edit your authored package and compile again when its behavior changes. `unmute deploy` handles SLNG; this route uses `lk agent`. On this page: * [Quickstart](#quickstart) - compile and create the first deployment * [Choose the project](#1-choose-the-project) - authentication and destination * [Prepare the package](#2-prepare-the-package) - target, build files and credentials * [The first deploy is create](#the-first-deploy-is-create) - create and save its identity * [Check it, and recover it](#check-it-and-recover-it) - status and a real interaction * [Every later deploy is deploy](#every-later-deploy-is-deploy) - update the existing agent * [Secrets](#secrets) - change values without rebuilding * [Advanced](#advanced) - regions, phone routes and customization * [Troubleshooting](#troubleshooting) - symptoms and fixes * [Where to go next](#where-to-go-next) ## Quickstart Start with a package that declares a LiveKit target named `livekit`. [Create a package](/deploy/going-live) first if you do not have one. Install the [LiveKit CLI](https://docs.livekit.io/reference/developer-tools/livekit-cli/) and prepare the runtime secret file described below. From the package root; replace both placeholders with your destination: ```sh Package root theme={null} lk cloud auth lk project list unmute validate . --target livekit unmute compile . --target livekit cd build/livekit lk --project "" agent create --region "" --secrets-file ../../.env.livekit lk --project "" agent status ``` `create` writes `livekit.toml` with the new agent ID and project. Keep it for later updates. The following sections explain each step. ## 1. Choose the project `lk cloud auth` links a project through your browser. This authenticates the CLI on your machine; it does not provision your model providers' keys. Use an account with access to manage agents in the destination project. `lk project list` shows linked projects. Pass `--project ""` on deployment commands so the destination is explicit. You can also set a default with `lk project set-default ""`. See [project selection](https://docs.livekit.io/reference/developer-tools/livekit-cli/projects/). On later runs, `livekit.toml` identifies the project and agent. The explicit project must match that file. Changing the CLI's default does not move an agent. ## 2. Prepare the package ### Set the target and models Declare `provider: livekit` and an exact supported framework `version:` in `targets.yaml`. See the [LiveKit target fields](/targets/livekit#target-fields) and [supported versions](/reference/targets-yaml#framework-versions-are-exact). The generated image supplies Python; you do not need a local Python environment to validate or compile. Choose [reasoning](/models/llm), [speech recognition](/models/stt), [speech generation](/models/tts), and [turn detection](/models/turn-detection) in the package, or use the target's model overrides. Provider parameters and credentials follow those bindings. Changing a model uses the same compile and deploy steps. `unmute validate` checks declarations and target support. Compilation also validates, then writes `build/livekit/`. Neither operation proves a provider will accept a request with your account and credentials. ### Use the generated build directory Run LiveKit commands from `build/livekit/`, where these files are generated: | File | Role | | -------------------------------- | -------------------------------------------------- | | `agent.py` | Worker and compiled prompts, tasks and tool wiring | | `pyproject.toml` | Python project manifest and selected dependencies | | `Dockerfile` and `.dockerignore` | Image build and file exclusions | | `tools/` | Copied local tool handlers, when declared | | `.env.example` | Environment names for this package and route | | `README.md` | Package-specific runbook | | `compile-report.json` | Resolved bindings and compiler decisions | The compiler supplies the project manifest and Dockerfile. No custom adapter or Dockerfile is needed for this route. LiveKit builds the image remotely from this directory; files elsewhere in the authored package are not its build context. See [LiveKit builds](https://docs.livekit.io/deploy/agents/builds/). ### Supply only the runtime values Declare secret names in the package as described in [credentials](/build/credentials). Supply their values separately. Create `.env.livekit` in the package root, outside the generated build directory, and exclude it from source control. This is a format example. Replace the name with a required name from your build's `.env.example`, then add only the other runtime values it needs: ```dotenv .env.livekit — package root, placeholders only theme={null} SERVICE_API_KEY=replace-with-the-provider-key ``` Obtain keys from the provider linked by your [model binding](/models/llm). Do not copy a whole development environment into this file. Remove unused names, blank placeholders, and local-only connection settings. | Value | Where it belongs | | -------------------------------------------------------- | -------------------------------------------------------- | | CLI authentication | The linked project on your machine | | Provider, tracing and tool credentials | Runtime secrets supplied to the deployed agent | | `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | Injected by LiveKit Cloud; omit from the upload | | Local SIP `REDIS_URL` | Local infrastructure; omit for managed Cloud SIP | | Non-secret settings a handler reads from its environment | May use the same runtime environment file | | Conversation variables | Package/session state; see [variables](/build/variables) | LiveKit excludes its three connection credentials from secret uploads. It does not create or revoke your provider keys. See [runtime secret storage](https://docs.livekit.io/deploy/agents/secrets/). ## The first deploy is `create` From `build/livekit/`, choose a supported worker region and create the agent: ```sh build/livekit/ theme={null} lk --project "" agent create --region "" --secrets-file ../../.env.livekit ``` Choose the region declared by your target, if any. See [region selection](#region-is-chosen-once) below. If the package needs no uploaded runtime values, omit `--secrets-file`. `create` registers a resource, writes `livekit.toml`, uploads the build context, and starts the image build and deployment. It expects no existing config with that filename. Use `deploy` for an existing resource. See LiveKit's [first deployment](https://docs.livekit.io/deploy/agents/quickstart/). | Name | What it identifies | | ------------------------------ | -------------------------------------------------------------- | | Package `name:` | The authored package | | Target name, such as `livekit` | The selected target and build directory | | Dispatch name | Package name joined to target name, such as `my-agent-livekit` | | Cloud agent ID | The resource created by LiveKit and saved in `livekit.toml` | Recompiling preserves `livekit*.toml`, `.env`, and `samples/*.json` within this build directory. It replaces everything else there. Keep authored changes in the package, and retain a backup of deployment config files. ## Check it, and recover it From `build/livekit/`, inspect the selected deployment: ```sh build/livekit/ theme={null} lk --project "" agent status lk --project "" agent list lk --project "" agent logs ``` A successful image build does not prove the worker is ready. Check its status and startup logs, then start a session with its dispatch name in the [Agent Console](https://docs.livekit.io/agents/start/console/) or your existing frontend. Ask one short question and confirm the agent receives it and answers it. A greeting alone does not prove caller input reached the model. Exercise one tool if the package uses tools. Read the new session's logs for provider and tool errors, without sharing secret values or sensitive conversation content. This is a deployment smoke check. Phone routes still need [carrier setup and a deployed call](/telephony/overview#point-the-carrier-at-the-deployment), and application testing still needs its own cases. If you lose the config, recover it using the existing ID from `agent list`: ```sh build/livekit/ theme={null} lk --project "" agent config --id "" ``` ## Every later deploy is `deploy` Change authored prompts, tool handlers, declarations or model bindings. Return to the package root before validating and compiling: ```sh Package root theme={null} unmute validate . --target livekit unmute compile . --target livekit cd build/livekit lk --project "" agent deploy ``` `deploy` builds a new image for the ID in `livekit.toml`. It does not read the authored files outside this directory. Target selection leaves other targets' builds untouched, so compile each target you intend to update. The secrets file is optional on update. Existing secrets remain unless you change them. If the CLI offers to import a discovered environment file, decline when you intend a code-only update. Use [secrets-only updates](#secrets) for deliberate credential changes. LiveKit rolls out new workers for new sessions and gives old workers up to an hour to finish active sessions. Repeat the status and interaction checks after the rollout. See [deployment management and rollback](https://docs.livekit.io/deploy/agents/managing-deployments/) for recovery options and plan limits. ## Secrets From `build/livekit/`, add or replace the values in your runtime file: ```sh build/livekit/ theme={null} lk --project "" agent update-secrets --secrets-file ../../.env.livekit lk --project "" agent secrets ``` The update merges supplied names into the existing set. Removing a line from the file does not delete the deployed secret. To remove names, prepare the complete set you want to retain, then replace the deployed set: ```sh build/livekit/ theme={null} lk --project "" agent update-secrets --secrets-file ../../.env.livekit --overwrite ``` `--overwrite` removes existing names absent from the supplied set. Check the retained file before running it. The command uses the same project access and agent identity as deployment. Both updates trigger a rolling restart without rebuilding the image. New sessions receive the new values. `agent secrets` displays names and timestamps, never values. Test a fresh session after updating a credential. See [LiveKit secret semantics](https://docs.livekit.io/deploy/agents/secrets/). Rotating a key has two separate parts: update this deployed value, then revoke the old key with its provider after confirming the replacement works. ## Advanced ### Region is chosen once On the LiveKit target, Unmute accepts `us-east`, `eu-central`, or `ap-south`, either singly or as a list without duplicates. Omission emits no region flag. Use an explicit `--region` when destination placement matters. This controls worker hosting. Provider inference locations, provider routing parameters and LiveKit media placement are separate settings. See [regional infrastructure](/optimization/regional-infrastructure). LiveKit documents a deployment's region as fixed after creation. To move, create in the new region and retire the old deployment after verification. For several regions, the generated README supplies one create command and one `livekit..toml` per region. Pass the matching `--config` on subsequent updates, secret changes and inspection commands. All those workers share the dispatch name. Routing may use another region when the nearest is at capacity. See [multi-region routing](https://docs.livekit.io/deploy/admin/regions/agent-deployment/) before relying on worker placement for strict locality. ### Telephony needs two more records For an inbound SIP route, the generated `telephony-setup.sh` creates the LiveKit trunk and dispatch rule. Run it from `build/livekit/` after deploying, with the matching project selected. It needs `lk`, `jq`, and the route values in `.env`; these local script inputs are separate from Cloud secret storage. Follow [LiveKit carrier setup](/telephony/livekit-twilio#create-the-livekit-records) for the full sequence. ### Renaming the agent breaks that rule Changing the package name changes the dispatch name. Within the same build directory, `deploy` still updates the resource ID in the preserved config. Renaming the target changes the build directory too: recover the existing agent config there with `lk agent config --id` before updating. An existing SIP dispatch rule keeps its old name. The setup script reuses that rule, so rerunning it alone does not fix the route. Deploy the new worker and confirm its dispatch name with `lk agent list`. Then list the rules with `lk sip dispatch list`, remove the stale rule with `lk sip dispatch delete `, and rerun `bash telephony-setup.sh`. The number is unrouted between deletion and recreation. Verify the rule names the new worker, then make a test call. For the `connector` route, redeploy the bridge from the new build: its `AGENT_NAME` also carries the dispatch name. ### Customize the supported inputs Use [model bindings](/models/llm), [tools](/build/tools/overview), and [LiveKit target fields](/targets/livekit#target-fields) first. Local Python handlers are supported; arbitrary neighboring modules and data files are not automatically copied. See [local handlers](/build/tools/python). Target `pins:` can override known catalog dependencies within validated bounds. It is not an arbitrary Python requirements list. Unmute exposes no authored Dockerfile override or general worker lifecycle hook. Generated edits disappear on compilation. For self-hosting, use the [generated LiveKit project](/targets/livekit) and [LiveKit's self-hosted deployment guide](https://docs.livekit.io/deploy/custom/deployments/). You supply your own LiveKit server URL and API credentials on that route. ## Troubleshooting | Symptom | Cause → fix | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Project or manifest not recognized | Wrong working directory or incomplete build → compile and run from `build/livekit/`, containing `pyproject.toml` and `Dockerfile`. | | Config already exists during create | This directory already identifies an agent → use `deploy`, or recover the intended config before proceeding. | | Project mismatch or wrong destination | CLI selection and config disagree → compare `lk project list` with `livekit.toml` and use the matching `--project`. | | Build passes, worker is not ready | Startup, dependency or provider failure → read `agent logs`; check `agent status` before testing. An idle deployment may have scaled to zero. | | Missing credentials | Required values were omitted or the key has the wrong provider scope → inspect names with `agent secrets`, then correct and update the required values. | | Provider rejects a parameter or region | Local validation does not verify provider account access → check the binding's provider documentation, correct the authored setting, compile and deploy. | | Missing shared module or data file | The file was not included by the compiler → use supported tool inputs; see [local handlers](/build/tools/python). | | Greeting works, caller input does not | The client may not publish microphone audio → check browser permission, selected input and mute state; inspect the session before changing models. | | New behavior is absent | Stale target build, wrong config or an older active session → compile the intended target, deploy its config and start a fresh session. | | Phone rings without an answer | Carrier routing, dispatch or runtime failure → follow the route's [telephony checks](/telephony/overview). | ## Where to go next The package-to-deployment workflow across targets. Generated files and supported target settings.