Ratel Docs

The console has no login. Anyone who reaches it is an admin. Ratel binds to 127.0.0.1 only: keep it behind your own proxy with authentication and TLS.

Install

git clone https://github.com/ratel-ai/ratel.git
cd ratel
cp .env.example .env

Set these in .env before the first start. Generate each secret with openssl rand -hex 32.

RATEL_ORG_NAME=Acme
BASE_URL=https://ratel.example.com
POSTGRES_PASSWORD=<generated>
TRACE_SIGNALS_HASH_SALT=<generated>

Then start it:

docker compose up -d --build --wait

Proxy

Point your proxy at 127.0.0.1:3000 and configure it so that:

/v1, /v2, /api/v1, /api/v2 and /api/mcp pass through without your login. SDKs and MCP clients authenticate with project keys. /api/health can pass too, for your monitor.
Everything else requires your login.
It preserves Host or sets X-Forwarded-Host. Otherwise console actions fail.

/api/cron/drain matters only with RATEL_CRON=external. It takes CRON_SECRET as a bearer: give your scheduler that route and nothing else.

TLS

Terminate it at the proxy. Keep BASE_URL on the https:// address: the console builds its snippets from it.

Processes

Compose runs two containers from the same image:

web serves the console and the API, and only queues background work.
worker runs it: analysis, sweeps, model calls.

A slow job never holds up a request. To run everything in one container, start the image without APP_ROLE.

Backups

All state is in the Postgres volume ratel_pgdata.

docker compose exec -T db pg_dump -U ratel ratel > ratel.sql      # back up
docker compose exec -T db psql -U ratel ratel < ratel.sql         # restore into an empty database

Keep .env too. A lost TRACE_SIGNALS_HASH_SALT splits old hashes from new.

Upgrades

Check out a tag or a commit, not a moving branch, then run docker compose up -d --build --wait.

Migrations run on boot and only add to the schema. To roll back, restore the dump you took before the upgrade and check out the earlier version.

Everyday commands

docker compose up -d --build --wait    # start, or update after a git pull
docker compose down                    # stop, keeping your data
docker compose logs -f web worker      # follow the logs
docker compose down --volumes          # stop and DELETE ALL DATA

Run on a server