unmute binary (installation), Docker
running for this LiveKit quickstart, and two API keys: one for the model that thinks (OPENAI_API_KEY) and
one for the SLNG speech models the scaffold uses (SLNG_API_KEY).
This page is written against the newest release. Run unmute --version to see
what you have, and upgrade if a flag here is missing from your build.
On this page:
- Scaffold and talk to it - three steps, one conversation
- Validate, develop, and compile - which command, when
- If something goes wrong - four symptoms, four fixes
The coding skill is optional and unrelated to
SLNG_API_KEY, which
authenticates the default speech models. This page uses the CLI directly;
Coding agents shows the assistant workflow.Scaffold and talk to it
1
Scaffold a package
Files created by unmute init
Files created by unmute init
agent.yaml is the agent,
instructions.md is its prompt, and
targets.yaml picks the target this package
compiles to. Unmute compiles to three targets: Pipecat, LiveKit,
or SLNG (see targets); this scaffold picks LiveKit
Agents. Their configuration pages list every supported key.
.env.example lists the keys to fill in. The scaffold uses SLNG speech
models for listening and speaking.2
Add your keys
.env and fill in only OPENAI_API_KEY and SLNG_API_KEY. The
secrets guide explains which names belong to the
package and which belong to its runtime.Where the LiveKit connection comes from
Where the LiveKit connection comes from
LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and LIVEKIT_URL point at a
LiveKit server, so they are absent from .env.example. unmute dev
supplies them locally; LiveKit Cloud or a self-hosted operator supplies
them at deploy time.unmute dev reads your shell, then .env and .env.local in the current
directory, then .env and .env.local in the package directory. Later
files win, so .env.local is a supported local alternative that can
override .env.3
Talk to it
What unmute dev runs
What unmute dev runs
unmute dev validates and compiles the package, builds its container,
starts it, and serves the browser page. The first run is slower because
Docker builds the image; later runs reuse it.Validate, develop, and compile
The quickstart useddev because it is the shortest path to a conversation.
The three commands serve different moments:
Run
unmute validate whenever you change the package. A warning is a real
difference worth reading, but it still exits 0. An error names the file and
line and exits 1.
All three commands take an optional package directory. With no argument they
use the current directory.
If something goes wrong
unmute dev stops and says docker compose is required
unmute dev stops and says docker compose is required
Docker is not running, or Compose is missing. This scaffold targets LiveKit,
whose local server stack runs in Docker Compose. Pipecat browser targets use
uv instead.Fix: start Docker and run the command again.The container stops, naming environment variables it did not find
The container stops, naming environment variables it did not find
The container starts, checks the keys the agent needs, and stops with the
names it did not find.Fix: fill them in
.env and run again.The browser page opens but nothing speaks
The browser page opens but nothing speaks
The container is running, so its log has the answer.Fix: look at
build/livekit/dev.log. It has the container’s whole
output. Add --verbose to follow the same log in your terminal while it
runs.unmute dev says the port is already in use
unmute dev says the port is already in use
This only happens for a port you passed yourself. With no
--port or
--bot-port, unmute dev picks a free one and prints the URL.Fix: either stop the run holding the port, or pass another one:
--port 8790 for the web page and --bot-port 7890 for the agent.Where to go next
Later, Build the agent continues with this samemy-agent package, so you will not run unmute init again when you get
there.
Coding agents
Let a supported assistant write the package for you.
How Unmute works
What the compiler did between your files and that container.