Skip to main content
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

Start with a package that declares a LiveKit target named livekit. Create a package first if you do not have one. Install the LiveKit CLI and prepare the runtime secret file described below. From the package root; replace both placeholders with your destination:
Package root
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 "<project-name>" on deployment commands so the destination is explicit. You can also set a default with lk project set-default "<project-name>". See project selection. 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 and supported versions. The generated image supplies Python; you do not need a local Python environment to validate or compile. Choose reasoning, speech recognition, speech generation, and 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: 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.

​
Supply only the runtime values

Declare secret names in the package as described in 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:
.env.livekit — package root, placeholders only
Obtain keys from the provider linked by your model binding. Do not copy a whole development environment into this file. Remove unused names, blank placeholders, and local-only connection settings. LiveKit excludes its three connection credentials from secret uploads. It does not create or revoke your provider keys. See runtime secret storage.

​
The first deploy is create

From build/livekit/, choose a supported worker region and create the agent:
build/livekit/
Choose the region declared by your target, if any. See region selection 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. 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:
build/livekit/
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 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, and application testing still needs its own cases. If you lose the config, recover it using the existing ID from agent list:
build/livekit/

​
Every later deploy is deploy

Change authored prompts, tool handlers, declarations or model bindings. Return to the package root before validating and compiling:
Package root
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 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 for recovery options and plan limits.

​
Secrets

From build/livekit/, add or replace the values in your runtime file:
build/livekit/
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:
build/livekit/
--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. 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

​
string or list of strings
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. 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.<region>.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 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 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 <rule-id>, 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, tools, and LiveKit target fields first. Local Python handlers are supported; arbitrary neighboring modules and data files are not automatically copied. See local handlers. 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 and LiveKit’s self-hosted deployment guide. You supply your own LiveKit server URL and API credentials on that route.

​
Troubleshooting

​
Where to go next

Going live

The package-to-deployment workflow across targets.

LiveKit project

Generated files and supported target settings.