Installation

Reverie is a Python package. It is not on PyPI, so you install it from its GitHub repository.

Requirements

Need	Why
Python 3.12 or newer	The package declares requires-python = ">=3.12".
A Chromium-family browser	Reverie opens its own browser window for each session.
An OpenRouter API key	One OPENROUTER_API_KEY covers the default setup: the Jev decision engine, the pilot (the multimodal model that runs your spec), and the text model.
A laya.cpp server (optional)	Only for local, offline decisions with the Laya engine (REVERIE_DECISION_ENGINE=laya). The default needs none.

Browser

Reverie starts a dedicated browser with a fresh profile per session. It never touches your own browser profile. It looks for the first of these on your PATH:

chromium, google-chrome-stable, google-chrome, brave, chromium-browser

To use another browser, set REVERIE_BROWSER to its name or full path:

export REVERIE_BROWSER=/path/to/chrome

If the variable points to a file that does not exist, or no browser is found, the session fails to start. See Troubleshooting.

Model API key

Create an OpenRouter key at openrouter.ai and put it in a .env file (see Configure). Without a key, a session that uses the default Jev engine refuses to start and tells you how to fix it.

Local Laya (optional)

Laya is the local, offline decision engine. Use it when you do not want to send page elements to a hosted service. Set REVERIE_DECISION_ENGINE=laya (or pass --engine laya to reverie start) and run one of:

• a laya.cpp server. Reverie talks to it over HTTP at http://127.0.0.1:8080 by default; change that with LAYA_BASE_URL. You build and run laya.cpp yourself; see Optional services for a helper script.
• MLX on Apple Silicon (see below), with LAYA_BACKEND=mlx.

Laya needs no key.

Install

With uv, from a clone

git clone https://github.com/r3c0nc1l3r/reverie
cd reverie
uv sync

Then run commands with uv run reverie ... from the clone.

To run Reverie in a container, see Run in Docker.

With uv, as a tool

uv tool install puts the reverie command on your PATH:

uv tool install git+https://github.com/r3c0nc1l3r/reverie

With pip

Use a virtual environment with Python 3.12 or newer.

pip install git+https://github.com/r3c0nc1l3r/reverie

Or, from a clone, for an editable install:

git clone https://github.com/r3c0nc1l3r/reverie
cd reverie
pip install -e .

Both routes install two commands that do the same thing: reverie and laya-agent, an older alias. This documentation uses reverie.

Optional: MLX on Apple Silicon

The mlx extra adds laya-mlx, which runs the local Laya decision engine in-process on Apple Silicon instead of through a laya.cpp server.

uv sync --extra mlx

Use it with REVERIE_DECISION_ENGINE=laya and LAYA_BACKEND=mlx. The default, auto, uses MLX only on an Apple Silicon Mac where laya_mlx is installed. Everywhere else it uses HTTP.

Configure

Run Reverie from the project you test. Reverie reads settings from your shell environment, then from .env files. The first value found wins. See How .env is loaded for the full list.

Copy the example file from the Reverie clone into your project:

cp /path/to/reverie/.env.example .env

Then edit .env. A minimal setup is one OpenRouter key:

TEXT_MODEL_PROVIDER=openrouter
OPENROUTER_API_KEY=your-openrouter-key

Jev (the decision engine), the pilot, and the text model all use it. The pilot and the text model call an OpenAI-compatible endpoint. TEXT_MODEL_PROVIDER picks the base URL, and OPENROUTER_API_KEY supplies the key.

To decide locally instead, add:

REVERIE_DECISION_ENGINE=laya
LAYA_BASE_URL=http://127.0.0.1:8080
``` Without a provider or `TEXT_MODEL_BASE_URL`, the endpoint defaults to `https://api.deepseek.com/v1` and the key comes from `TEXT_MODEL_API_KEY`. Comments must be on their own line: everything after `=` is the value.

:::tip
Keep API keys out of your repositories. Put them in `~/.config/reverie/.env` and restrict the file, so every project shares them:

```bash
mkdir -p ~/.config/reverie
printf 'OPENROUTER_API_KEY=your-openrouter-key\n' > ~/.config/reverie/.env
chmod 600 ~/.config/reverie/.env

The project’s own .env then holds only settings, and wins over the user file when both set a variable. :::

See Models and providers for other providers, a separate pilot endpoint and the decision engines, and the configuration reference for every variable.

Optional services

scripts/agent-services.sh in the clone starts, stops, and checks the optional local services: laya.cpp (only for local Laya) and a local text-to-speech server.

scripts/agent-services.sh start
scripts/agent-services.sh status
scripts/agent-services.sh stop

The script finds laya.cpp through LAYA_CPP_DIR and the Kitten Python environment through KITTEN_PYTHON. Set LOCAL_TTS=kokoro to start Kokoro instead of Kitten. Set LAYA_PORT and KITTEN_PORT to change ports. Logs and pid files go in laya-agent/services under $XDG_RUNTIME_DIR (or ~/.cache). Narration is optional; see Narration.

Verify

reverie --version

With a clone and uv, run uv run reverie --version. You should see reverie followed by a version number. Then continue to the first run.