[opensourcedex]

ratel is a free, open source monitoring & observability project written in TypeScript and released under MIT. It has 563 GitHub stars, 32 forks and 23 open issues, and was last pushed 37 hours ago. On this registry it ranks #263 of 271 tracked projects in Monitoring & Observability, with 5 head-to-head comparisons available. It gained 1 stars over the last 2 tracked days.

What is ratel?

Ratel is a self-hosted observability and self-improvement platform for AI agents that ingests an agent's traces and its catalog of tools and skills, then shows where the agent fails and which changes would help — aimed at anyone building or running an agent who wants that data to stay on their own machines.

What it is

Ratel is a platform an AI agent sends its traces to, together with its catalog of tools and skills. It runs as one application and one Postgres database and needs nothing else. That single application holds the console pages you read and act on; ingest and catalog APIs covering OTLP traces and logs, SDK events, catalog pull, and skills and intent graph sync, authenticated with per-project API keys; and background jobs on a durable queue in Postgres that is drained every minute inside the application, so there is no separate worker or scheduler to run. TypeScript and Python SDKs are included, and the project is MIT licensed.

The problem it addresses is the distance between having trace traffic and knowing what to change. Ratel closes it with readings derived as jobs over a ledger of the agent's turns: agent health signals, workflows and self-corrections, topics, intent clusters and the intent graph, the tool explorer and match quality. Model keys are optional, and with no key Ratel makes no outbound model call, readings that need a model report themselves skipped, workflows keep their tool-order names and topics are named from their own asks. It lives in the OpenTelemetry and MCP ecosystem, ingesting OTLP and exposing an MCP server, instead of requiring a separate collector, worker and scheduler stack to be assembled and operated.

Key capabilities

  • Ingests OTLP traces and logs alongside SDK events and catalog data, authenticated with per-project API keys created under Settings > API keys and shown once.
  • Derives agent health signals, workflows and self-corrections, topics, intent clusters and the intent graph, the tool explorer and match quality as jobs over a ledger of the agent's turns.
  • Carries its own job system: a durable queue in Postgres drained every minute inside the application, with no separate worker or scheduler.
  • Serves an MCP server at POST /api/mcp with Bearer authentication so an agent can query Ratel, with copy-paste setup for Claude Code, Claude Desktop, Cursor and VS Code.
  • Ships TypeScript and Python SDKs plus a curl snippet that posts a single span to the traces endpoint and answers 202.
  • Keeps Tasks, Ship for testing a fix before it ships, session replay and the improvement-loop tools behind RATEL_EXPERIMENTAL_FEATURES=1, which adds 9 tools to the MCP server.

Who uses it and how

  • Teams running an agent on their own infrastructure deploy it with Docker Compose as one application and one Postgres database, with no external worker or scheduler to operate.
  • Developers wiring an agent into the console connect over MCP, for example with claude mcp add --transport http ratel /api/mcp --header "Authorization: Bearer $RATEL_API_KEY", from Claude Code, Claude Desktop, Cursor or VS Code.
  • Evaluators load 30 days of sample activity for a project called Site Copilot with docker compose --profile demo run --rm demo; a fresh install also seeds it once per organization, marked as sample data.
  • Small installations are expected: Docker with Compose 2.24 or later, roughly 5 GB of free disk and 4 GB of RAM for Docker (8 GB is comfortable), with a first build of about five minutes.

Getting started

Clone the repository, run docker compose up -d --build --wait and open http://localhost:3000; no configuration is needed, though RATEL_PORT, RATEL_DB_PORT and BASE_URL in .env handle port conflicts.

How it compares

No comparable products are named in the material available for this listing, so Ratel stands alone in this registry. Its position in the category is defined by being MIT licensed and self-hosted as one application and one Postgres database, with no separate worker or scheduler to operate.

When to use it — and when not to

Choose it when agent behaviour data must stay on your own machines and you are willing to run the Compose stack and its Postgres database yourself; it will not suit teams that want a hosted service or a managed database. The README's server section opens with a warning that the console has no login, so anyone who reaches it can use it, and it should not be exposed without protection. Experimental features are off by default, and some console pages take a couple of minutes to fill in once demo data is seeded.

project readme (upstream, from github) — read inline

Ratel

See what your AI agent gets wrong, and what to change. On your own infrastructure.

Docs • Skills • Discord

GitHub stars Discord license

Introduction

Ratel is a self-hosted platform for AI agents. Your agent sends it traces and its catalog of tools and skills. Ratel reads that traffic and shows you what the agent gets wrong, what people ask it for, and which changes would make it find and finish more.

It is for anyone building or running an agent who wants to see how it behaves and keep that data on their own machines. It runs as one application and one Postgres database, and it needs nothing else:

  • Console: the pages you read and act on. See What is in the console.
  • Ingest and catalog APIs: OTLP traces and logs, SDK events, catalog pull, skills and intent graph sync, authenticated with per-project API keys.
  • Background jobs: a durable queue in Postgres, drained every minute inside the application. There is no separate worker or scheduler to run.
  • Readings: what Ratel works out from the traffic, as jobs over a ledger of your agent's turns: Agent health signals, workflows and self-corrections, topics, intent clusters and the intent graph, the tool explorer, and match quality.

Model keys are optional. With no key, Ratel makes no outbound model call. The readings that need a model report themselves skipped, workflows keep their tool-order names, and topics are named from their own asks.

Quick Start

You need Docker with Compose 2.24 or later, network access to pull images and packages, about 5 GB of free disk in the Docker VM (the app and Postgres images take under 1 GB, the optional demo image 1.2 GB more, plus your data) and 4 GB of RAM for Docker (8 GB is comfortable). The first build takes about 5 minutes.

On your machine

git clone https://github.com/ratel-ai/ratel.git
cd ratel
docker compose up -d --build --wait

Open http://localhost:3000. No configuration is needed.

If port 3000 or 5432 is taken, set RATEL_PORT and RATEL_DB_PORT in .env (copy .env.example) and set BASE_URL to the address you open, such as http://localhost:3950. The console's snippets and the demo's links use BASE_URL.

If docker compose up --wait fails, read docker compose logs db web worker. A full Docker disk shows up only in the db log (No space left on device). On a small machine the worker can report unhealthy for the first minutes after a restart, while it catches up on queued jobs; it usually settles by itself.

First steps

  1. In the console, open Settings > API keys and create a key. It is shown once.
  2. Send a first trace. The same page shows a TypeScript and a curl snippet with your endpoint; the curl one posts a single span to the traces endpoint and answers 202. Set RATEL_API_KEY to the key.
  3. To let an agent query Ratel, connect it over MCP: POST /api/mcp with Authorization: Bearer . The console's Integrations page has copy-paste setup for Claude Code, Claude Desktop, Cursor and VS Code, for example claude mcp add --transport http ratel /api/mcp --header "Authorization: Bearer $RATEL_API_KEY". Details are in apps/web/lib/mcp/README.md.

Experimental features

Tasks and Ship, testing a fix before it ships, session replay and the improvement-loop MCP tools are off by default. Add RATEL_EXPERIMENTAL_FEATURES=1 to .env and run docker compose up -d --build --wait to turn them on; remove the line (or set 0) and run it again to turn them off. With them on, Tasks becomes a page of its own in the rail and replaces the Tasks tab under Agent health, and the MCP server lists 9 more tools (40 without).

Explore with demo data (optional)

docker compose --profile demo run --rm demo

A fresh install seeds this sample project, Site Copilot, by itself the first time the console opens with no project: 30 days of agent activity, marked as sample data, seeded once per organization (deleting it does not bring it back). Some pages fill in over the next couple of minutes. This command replaces it with a fresh copy, or restores it after a delete.

On a server

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.

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 with docker compose up -d --build --wait. 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, because the SDKs and MCP clients authenticate with API keys (bearer project keys). /api/health can pass too, for your monitor.
  • Everything else requires your login. That includes /api/cron/drain, which only matters if you set RATEL_CRON=external; it takes CRON_SECRET as a bearer, so give your scheduler that route and nothing else.
  • It preserves Host or sets X-Forwarded-Host, otherwise console actions fail.

Model keys are optional, and every field is explained in .env.example.

TLS. Terminate it at the proxy and keep BASE_URL on the https:// address, since the console's snippets are built from it.

Backups. All state is in the Postgres volume (ratel_pgdata). Dump it with docker compose exec -T db pg_dump -U ratel ratel > ratel.sql, and restore into an empty database with docker compose exec -T db psql -U ratel ratel < ratel.sql. Keep .env too: a lost TRACE_SIGNALS_HASH_SALT splits old hashes from new.

Upgrades. Check out a tag or a commit rather than following a moving branch, then run docker compose up -d --build --wait. Migrations run on boot and only add to the schema, so a rollback means restoring the dump you took before the upgrade and checking out the earlier version.

Everyday commands

docker compose up -d --build --wait    # start, or update after a git pull; migrations run on boot
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

Two containers run the app from the same image: web serves the console and the API and only queues background work, and worker runs it (analysis, sweeps, model calls), so a slow job never holds up a request. To run everything in one container instead, start the image without APP_ROLE.

POSTGRES_PASSWORD is read only when the database is first created. Changing it later means deleting the data with the last command.

What is in the console

An organization holds projects, and each project is one agent's view:

Page What it shows
Overview The project at a glance: activity over the last 7 or 30 days, and what needs attention.
Agent health What your agent gets wrong. Summary lists the issues, Tasks follows what people tried to do down to each session, and Self-corrections lists the times the agent retried, switched tools, gave up or apologized. The Summary also prints as a report.
Traces Every run step by step, with spans, operations and logs, and two traces side by side.
Catalog Every tool and skill your agent can use, and how each one is found. Test a search ranks a prompt against the live catalog, with what-if edits.
Intents What people ask for. All intents lists the topics, Flows shows what people want next, ask after ask, and Map lays the intents out.
Improvements Fixes is the one list of changes that would make your agent find and finish more. Quality measures how well searches find the right tool, with misses, description rewrites and experiments. Adaptive ranking puts the tool your agent needs first, using what people asked before.
Settings Projects general settings, API keys, SDK events under Developer, and a danger zone.

Repo layout

apps/
└── web/                       # @ratel/platform: the console and APIs
packages/
├── brand/                     # @ratel/brand: palette, fonts and logo assets
├── design-system/             # @ratel/design-system: semantic tokens and UI primitives
└── sdk/                       # Ratel SDK documentation; the SDK code will move here later
src/                           # Ratel SDK: core (Rust), sdk, adapters, rankers, telemetry
scripts/                       # Repository checks and release tooling
docs/
├── adr/                       # Architecture decision records
└── assets/                    # Images and other static assets
ee/                            # Manifest for the Enterprise modules

The application's own layout and commands are in apps/web/README.md, and the layers of its core in apps/web/lib/README.md.

Development

Ratel Platform

Prerequisites: Node 24+ and pnpm 10.28+, with Docker for the platform's Postgres.

Ratel SDK

Prerequisites: The Rust workspace and the SDKs' native addons need Rust stable (pinned via rust-toolchain.toml). The Python SDK also needs Python 3.11 and uv.

Contributing

License

The ratel-ai-core engine is licensed under Apache-2.0, an explicit patent grant for the engine others embed. Everything else (the platform application, SDKs, telemetry helpers, examples) is MIT. See ADR-0009 for the rationale.

Frequently asked questions

Is ratel free to use?

ratel is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does ratel do?

The self-improvement layer for AI agents. Ratel reads your agent's traces, finds what fails, recommends fixes and runs evals on real sessions before you ship. S

What is ratel written in?

ratel is primarily written in TypeScript. Its source is publicly available at https://github.com/ratel-ai/ratel, and it has 563 GitHub stars.