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 brings in the engine and Python itself.

RequirementsCopy Anchor Link

InstallCopy Anchor Link

One command installs the cuelo CLI, verifies it against the release checksums, and adds it to your PATH. If uv is installed, it also sets up the matching engine.

curl -fsSL https://setup.cuelo.dev/install | bash

Check it:

cuelo --version

CLI and engineCopy Anchor Link

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.

ExtrasCopy Anchor Link

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

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.

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 keysCopy Anchor Link

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

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.

Download the turn-taking modelsCopy Anchor Link

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:

cuelo models pull --all

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

Check that it worksCopy Anchor Link

cuelo start

cuelo machine check

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

Upgrade and uninstallCopy Anchor Link

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 sourceCopy Anchor Link

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

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.

TroubleshootingCopy Anchor Link