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

# Quickstart

> Scaffold an agent, add two keys, and talk to it in your browser.

The quickstart scaffolds a package, adds two keys, and puts you in a browser
conversation with the agent.

You need the `unmute` binary ([installation](/start/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](#scaffold-and-talk-to-it) - three steps, one conversation
* [Validate, develop, and compile](#validate-develop-and-compile) - which command, when
* [If something goes wrong](#if-something-goes-wrong) - four symptoms, four fixes

<Note>
  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](/start/coding-agents) shows the assistant workflow.
</Note>

## Scaffold and talk to it

<Steps>
  <Step title="Scaffold a package">
    ```sh theme={null}
    unmute init my-agent
    cd my-agent
    ```

    <Accordion title="Files created by unmute init">
      ```text theme={null}
      created my-agent/agent.yaml
      created my-agent/.env.example
      created my-agent/.gitignore
      created my-agent/instructions.md
      created my-agent/targets.yaml
      created my-agent/tools/end_call.yaml
      ```

      [`agent.yaml`](/reference/agent-yaml) is the agent,
      `instructions.md` is its prompt, and
      [`targets.yaml`](/reference/targets-yaml) picks the target this package
      compiles to. Unmute compiles to three targets: Pipecat, LiveKit,
      or SLNG (see [targets](/targets/overview)); 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.
    </Accordion>

    <Tip>
      Run `unmute init` with no name in a terminal and you get an interactive
      console that asks for the name, the models, and the target instead.
    </Tip>
  </Step>

  <Step title="Add your keys">
    <CodeGroup>
      ```sh Bash theme={null}
      cp .env.example .env
      ```

      ```powershell PowerShell theme={null}
      Copy-Item .env.example .env
      ```
    </CodeGroup>

    Open `.env` and fill in only `OPENAI_API_KEY` and `SLNG_API_KEY`. The
    [secrets guide](/reference/secrets) explains which names belong to the
    package and which belong to its runtime.

    <Accordion title="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`.
    </Accordion>
  </Step>

  <Step title="Talk to it">
    ```sh theme={null}
    unmute dev
    ```

    Your browser opens automatically. Allow the microphone, press the button,
    and say hello.

    <Accordion title="What unmute dev runs">
      ```text theme={null}
      compiled build/livekit
      building and starting the container...

        ▸ http://localhost:8765/?agent=my-agent-livekit
          ctrl-c to stop  ·  logs: build/livekit/dev.log
      ```

      `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.
    </Accordion>

    Press ctrl-c when you are done. The container is stopped and removed for
    you.
  </Step>
</Steps>

## Validate, develop, and compile

The quickstart used `dev` because it is the shortest path to a conversation.
The three commands serve different moments:

| Command           | What it does                                                              |
| ----------------- | ------------------------------------------------------------------------- |
| `unmute validate` | checks the package against its targets without writing or running a build |
| `unmute dev`      | validates, compiles one target, runs it locally, and opens the browser    |
| `unmute compile`  | writes the compiled target projects without starting them                 |

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Where to go next

Later, [Build the agent](/build/your-first-agent) continues with this same
`my-agent` package, so you will not run `unmute init` again when you get
there.

<Columns cols={2}>
  <Card title="Coding agents" icon="bot" href="/start/coding-agents">
    Let a supported assistant write the package for you.
  </Card>

  <Card title="How Unmute works" icon="settings" href="/start/how-unmute-works">
    What the compiler did between your files and that container.
  </Card>
</Columns>