Get Roux
running.

Prerequisites

You need three things before you start:

• Docker & Docker Compose — all services run in containers.
• At least one LLM API key — see Step 2. Free options exist.
• Git

That's it. Postgres, Neo4j, Redis, and Celery all spin up automatically via Compose. No local database installation required.

Clone and configure

Clone the repo and copy the environment template.

git clone https://github.com/wastrilith2k/roux companion-framework
cd companion-framework
cp .env.example .env

Open .env in your editor. You'll fill in API keys in the next step and set your database passwords in Step 4.

Add your LLM API keys

Roux supports multiple providers with automatic failover. You need at least one. For the cheapest setup, use OpenRouter with free models. For production quality, use Fireworks (primary) + OpenAI (embeddings and tool calls).

Add whichever keys you have to .env. Roux uses whatever's available and skips what isn't.

Set your database passwords

Change the two default passwords in .env before starting any services.

POSTGRES_PASSWORD=your_secure_password
NEO4J_GRAPHITI_PASSWORD=your_secure_password

Start the stack

Choose development (hot-reload) or production mode:

# Development — with hot-reload
docker compose -f docker-compose.dev.yml up -d

# Production
docker compose up -d

First run will pull images and run database migrations automatically. Give it a minute, then check that all containers are up:

docker compose ps

Access your instance

Everything should be running. Here's where to find it:

The observation dashboard shows the same live view as demo.getroux.dev/observe — episodes forming, facts being extracted, and the relationship graph evolving in real time.