# Installation (/installation)

Cuelo has two parts: the **`cuelo` CLI**, a single binary you install once,
and the **engine**, the Python package that runs endpoints and serves the
dashboard. The installer gives you the CLI, and [uv](https://docs.astral.sh/uv/)
brings in the engine and Python itself.

## Requirements [#requirements]

|            |                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Python** | 3.12 or newer, managed by uv for you. Only needed directly for pip installs.                                                      |
| **OS**     | macOS (Apple Silicon and Intel), Linux (x86_64, arm64, glibc 2.17+), Windows (x86_64, arm64)                                      |
| **uv**     | Needed to run endpoints: it fetches Python and the engine. [Install uv](https://docs.astral.sh/uv/getting-started/installation/). |
| **Memory** | About 200 MB per server process, or about 1 GB with the MaAI turn-taking models (PyTorch)                                         |
| **Keys**   | One speech provider (Smallest by default) and one LLM provider                                                                    |

<Callout title="Which Python?">
If `python3 --version` says 3.11 or older, let uv fetch a newer one. Add `--python 3.13` to the
install command and uv downloads it for the tool alone.
</Callout>

## Install [#install]

One command installs the `cuelo` CLI, verifies it against the release
checksums, and adds it to your `PATH`. If [uv](https://docs.astral.sh/uv/) is
installed, it also sets up the matching engine.

<Tabs items={["macOS & Linux","Windows","Homebrew","uv / pip","Docker"]}>
<Tab value="macOS & Linux">
```bash
curl -fsSL https://setup.cuelo.dev/install | bash
```

Installs to `~/.cuelo/bin`. A specific version:
`curl -fsSL https://setup.cuelo.dev/install | bash -s -- v0.2.0`. The CLI
alone, without the engine: add `--no-engine`.
</Tab>

<Tab value="Windows">
```powershell
powershell -c "irm setup.cuelo.dev/install.ps1 | iex"
```

Installs to `%USERPROFILE%\.cuelo\bin` and adds it to your user `PATH`.
Open a new terminal afterwards.
</Tab>

<Tab value="Homebrew">
```bash
brew install thoughtsinc/tap/cuelo
```

Brings in `uv` as a dependency, so `cuelo start` fetches the engine on first
run.
</Tab>

<Tab value="uv / pip">
Install the engine and CLI together as a Python package, with the extras you
want (see [Extras](#extras)):

```bash
uv tool install --python 3.13 "cuelo[server,config,silero,maai,smallest,openai,anthropic]"
```

```bash
pip install "cuelo[server,config,silero,maai,smallest,openai,anthropic]"
```
</Tab>

<Tab value="Docker">
```bash
docker pull ghcr.io/thoughtsinc/cuelo
docker run --rm --init -p 4141:4141 --env-file .env -e CUELO_API_KEY=sk-... ghcr.io/thoughtsinc/cuelo
```

The image has the engine, CLI, dashboard and turn-taking weights, with
CPU-only PyTorch. It serves the default endpoint on port 4141. A public bind
needs `CUELO_API_KEY`. See [Security](/ship/security).
</Tab>
</Tabs>

Check it:

```bash
cuelo --version
```

<Callout title="What the installer does">
It detects your OS and CPU, downloads the matching binary from the GitHub release, refuses it if
the SHA-256 doesn't match, installs to `~/.cuelo/bin`, and adds that to your shell profile. Then,
if `uv` is available, it runs `uv tool install` for the matching engine version. Read it first:
`curl -fsSL https://setup.cuelo.dev/install | less`.
</Callout>

### CLI and engine [#cli-and-engine]

The **CLI** (`cuelo`) is a single Go binary. The **engine** is the Python
package `cuelo` that the CLI runs. The installers give you the CLI, and the
engine arrives in one of three ways:

- the installer installs it with uv (when uv is present),
- `cuelo start` fetches it through uv on first run,
- `cuelo init` and `cuelo dev` install it into each project's own environment.

So uv is the one prerequisite for running endpoints. Python itself is handled
by uv.

### Extras [#extras]

When you install the engine yourself with uv or pip, extras choose the providers
and models it includes. The installers use the recommended set.

| Extra                                                       | Adds                      | You need it for                                                                 |
| ----------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------- |
| `server`                                                    | Starlette, Uvicorn, httpx | serving the Realtime API, dashboard and HTTP tools. **Almost always.**          |
| `config`                                                    | PyYAML, jsonschema        | reading `config.cuelo`                                                          |
| `silero`                                                    | onnxruntime, numpy        | the VAD and the ONNX turn models: turn-1-mini, smart-turn, backchannel-detector |
| `maai`                                                      | PyTorch, einops           | MaAI interruptions and backchannels (the default). About 1 GB.                  |
| `smallest`, `deepgram`, `elevenlabs`, `cartesia`, `inworld` | httpx, websockets         | that vendor's STT and TTS                                                       |
| `assemblyai`, `soniox`                                      | websockets                | that vendor's STT                                                               |
| `openai`                                                    | openai                    | OpenAI, Cerebras, OpenRouter, any OpenAI-compatible LLM                         |
| `anthropic`                                                 | anthropic                 | Claude models                                                                   |
| `postgres`, `mysql`                                         | psycopg, PyMySQL          | storing calls in Postgres or MySQL instead of SQLite                            |

**Without PyTorch:** drop `maai`. Cuelo falls back to the small
backchannel detector for interruptions and a VAD rule for backchannels. That
uses about a fifth of the memory and is roughly ten times cheaper per call. See
[Turn-taking](/conversation).

```bash
uv tool install "cuelo[server,config,silero,smallest,openai,anthropic]"
```

To add an extra later, re-run `uv tool install` with the new list and `--force`.

## Add your keys [#add-your-keys]

Cuelo reads credentials from a `.env` file in the current directory, or from
the environment. They never go in `config.cuelo`.

```bash title=".env"
SMALLEST_API_KEY=...        # speech: STT and TTS
CEREBRAS_API_KEY=...        # LLM: or ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY
```

The default agent uses the first LLM it finds a key for: Cerebras, then
Anthropic, OpenAI and OpenRouter. Every provider's variable is listed in
[Environment variables](/reference/environment).

## Download the turn-taking models [#download-the-turn-taking-models]

Model weights download on first use, pinned to a revision and checked by
sha256. To fetch them ahead of time, for example before a demo or in a Docker
image:

```bash
cuelo models pull --all
```

They go to `~/.cache/cuelo/models`. Set `CUELO_MODELS` to move the cache.

## Check that it works [#check-that-it-works]

<Steps>
<Step>
### Start the default endpoint [#start-the-default-endpoint]

```bash
cuelo start
```

This opens the dashboard on [http://127.0.0.1:4141](http://127.0.0.1:4141).
Press **Connect** on the Talk page and say hello.
</Step>

<Step>
### Measure your machine [#measure-your-machine]

```bash
cuelo machine check
```

This streams real speech through the turn-taking stack and reports how many
concurrent calls your machine handles in real time.
</Step>

<Step>
### Create a project [#create-a-project]

```bash
cuelo init my-agent && cd my-agent
cuelo doctor        # config, credentials, generated code, imports
cuelo dev
```

The first `cuelo dev` installs the project's environment with uv.
</Step>
</Steps>

## Upgrade and uninstall [#upgrade-and-uninstall]

```bash
curl -fsSL https://setup.cuelo.dev/install | bash   # upgrade: re-run the installer
brew upgrade cuelo                                  # Homebrew
uv tool upgrade cuelo                               # the engine, when installed with uv
rm -rf ~/.cuelo && uv tool uninstall cuelo          # uninstall
```

Projects pin the engine version they were generated with. After upgrading the
CLI, run `cuelo generate` in a project to move it to the new engine.

## From source [#from-source]

To work on Cuelo itself, or to run the latest `main`:

```bash
git clone https://github.com/thoughtsinc/cues-harness && cd cues-harness
make setup          # Node, Python and Go dependencies
make cuelo          # bin/cuelo with the dashboard embedded
source .bashrc      # puts bin/ on PATH
```

Point a project at your checkout with
`cuelo generate --engine-path ../cues-harness/engine`. See
[Contributing](/contributing).

## Troubleshooting [#troubleshooting]

| Symptom                                                     | Fix                                                                                         |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `port 4141 is in use; is cuelo already running?`            | Stop the other server, or pass `--port 5000`.                                               |
| `MissingCredentialError: ... set SMALLEST_API_KEY in .env`  | The `.env` file must be in the directory you run from, or export the variable.              |
| `ModuleNotFoundError: starlette` (or `yaml`, `onnxruntime`) | An extra is missing. Re-install with `server`, `config` or `silero`.                        |
| Interruptions trigger on "yeah"                             | `maai` isn't installed, so Cuelo fell back to a lighter detector. Install the `maai` extra. |
| Slow first call                                             | Weights are downloading. Run `cuelo models pull --all` first.                               |
| `refusing to serve on 0.0.0.0 without an API key`           | Set `CUELO_API_KEY` (or `serve.api_keys`). See [Security](/ship/security).                  |