Skip to content
Back to search

ratel

Context engineering for AI agents. ~80% fewer tokens. Fix tool overload. Skills and memory with in-process BM25 and semantic retrieval. Progressive Disclosure. No vector DB.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ratel-ai/ratel with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ratel-ai/ratel'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ratel-ai--ratel/badge.svg)](/listings/ratel-ai--ratel)

HTML

<a href="/listings/ratel-ai--ratel"><img src="/api/listings/ratel-ai--ratel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Guides: [Quickstart](https://docs.ratel.sh/docs/quickstart) · [TypeScript SDK](https://docs.ratel.sh/docs/sdks/typescript) · [Python SDK](https://docs.ratel.sh/docs/sdks/python)

Examples: [Vercel AI SDK](examples/ai-sdk/README.md) · [Pydantic AI](examples/pydantic-ai/README.md)

Typescript

Install the SDK first:

pnpm add @ratel-ai/sdk

Then create and use your Catalogs:

import { readFile } from "node:fs/promises";
import {
  SkillCatalog,
  ToolCatalog,
  getSkillContentTool,
  invokeToolTool,
  searchCapabilitiesTool,
} from "@ratel-ai/sdk";

const catalog = new ToolCatalog();
catalog.register({
  id: "read_file",
  name: "read_file",
  description: "Read a file from local disk.",
  inputSchema: { type: "object", properties: { path: { type: "string" } } },
  outputSchema: { type: "object", properties: { contents: { type: "string" } } },
  execute: async ({ path }) => ({ contents: await readFile(path, "utf8") }),
});

const skills = new SkillCatalog();
skills.register({
  id: "inspect-local-file",
  name: "inspect-local-file",
  description: "Inspect a local file before answering questions about it.",
  tools: ["read_file"],
  body: "Read the requested file, then ground your answer in its contents.",
});

// use the following as tools in your agent framework
const search = searchCapabilitiesTool(catalog, skills);
const invoke = invokeToolTool(catalog);
const loadSkill = getSkillContentTool(skills);

Python

Install the SDK first:

pip install ratel-ai

Then create and use your Catalogs:

from ratel_ai import (
    ExecutableTool,
    Skill,
    SkillCatalog,
    ToolCatalog,
    get_skill_content_tool,
    invoke_tool_tool,
    search_capabilities_tool,
)

catalog = ToolCatalog()
catalog.register(ExecutableTool(
    id="read_file",
    name="read_file",
    description="Read a file from local disk.",
    input_schema={"properties": {"path": {"type": "string"}}},
    execute=lambda args: {"contents": open(args["path"]).read()},
))

skills = SkillCatalog()
skills.register(Skill(
    id="inspect-local-file",
    name="inspect-local-file",
    description="Inspect a local file before answering questions about it.",
    tools=["read_file"],
    body="Read the requested file, then ground your answer in its contents.",
))

# use the following as tools in your agent framework
search = search_capabilities_tool(catalog, skills)
invoke = invoke_tool_tool(catalog)
load_skill = get_skill_content_tool(skills)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 172 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <h1>Ratel</h1>
  3. <p>See what your AI agent gets wrong, and what to change. On your own infrastructure.</p>
  4. <p>
  5. <a href="https://docs.ratel.sh">Docs</a> •
  6. <a href="https://github.com/ratel-ai/skills">Skills</a> •
  7. <a href="https://discord.gg/75vAPdjYqT">Discord</a>
  8. </p>
  9. <p>
  10. <a href="https://github.com/ratel-ai/ratel/stargazers"><img src="https://img.shields.io/github/stars/ratel-ai/ratel?style=social" alt="GitHub stars" /></a>
  11. <a href="https://discord.gg/75vAPdjYqT"><img src="https://img.shields.io/discord/1478702964003705015?label=Discord&logo=discord&logoColor=white&color=5865F2" alt="Discord" /></a>
  12. <a href="#license"><img src="https://img.shields.io/badge/license-Apache--2.0%20%26%20MIT-blue" alt="license" /></a>
  13. </p>
  14. </div>
  15. <div align="center">
  16. <img src="./docs/assets/ratel-flow-demo.gif" width="960" alt="Ratel flow animation" />
  17. </div>
  18. ## Introduction
  19. 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.
  20. 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:
  21. - **Console:** the pages you read and act on. See [What is in the console](#what-is-in-the-console).
  22. - **Ingest and catalog APIs:** OTLP traces and logs, SDK events, catalog pull, skills and intent graph sync, authenticated with per-project API keys.
  23. - **Background jobs:** a durable queue in Postgres, drained every minute inside the application. There is no separate worker or scheduler to run.
  24. - **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.
  25. 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.
  26. ## Quick Start
  27. **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.
  28. ### On your machine
  29. ```sh
  30. git clone https://github.com/ratel-ai/ratel.git
  31. cd ratel
  32. docker compose up -d --build --wait
  33. ```
  34. Open `http://localhost:3000`. No configuration is needed.
  35. 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`.
  36. 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.
  37. ### First steps
  38. 1. In the console, open **Settings > API keys** and create a key. It is shown once.
  39. 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.
  40. 3. To let an agent query Ratel, connect it over MCP: `POST <BASE_URL>/api/mcp` with `Authorization: Bearer <project key>`. 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 <BASE_URL>/api/mcp --header "Authorization: Bearer $RATEL_API_KEY"`. Details are in [apps/web/lib/mcp/README.md](apps/web/lib/mcp/README.md).
  41. ### Experimental features
  42. 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).
  43. ### Explore with demo data (optional)
  44. ```sh
  45. docker compose --profile demo run --rm demo
  46. ```
  47. 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.
  48. ### On a server
  49. > **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.
  50. ```sh
  51. git clone https://github.com/ratel-ai/ratel.git
  52. cd ratel
  53. cp .env.example .env
  54. ```
  55. Set these in `.env` **before the first start**. Generate each secret with `openssl rand -hex 32`:
  56. ```sh
  57. RATEL_ORG_NAME=Acme
  58. BASE_URL=https://ratel.example.com
  59. POSTGRES_PASSWORD=<generated>
  60. TRACE_SIGNALS_HASH_SALT=<generated>
  61. ```
  62. Then start it with `docker compose up -d --build --wait`. Point your proxy at `127.0.0.1:3000`, and configure it so that:
  63. - `/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.
  64. - 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.
  65. - It preserves `Host` or sets `X-Forwarded-Host`, otherwise console actions fail.
  66. Model keys are optional, and every field is explained in `.env.example`.
  67. **TLS.** Terminate it at the proxy and keep `BASE_URL` on the `https://` address, since the console's snippets are built from it.
  68. **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.
  69. **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.
  70. ### Everyday commands
  71. ```sh
  72. docker compose up -d --build --wait # start, or update after a git pull; migrations run on boot
  73. docker compose down # stop, keeping your data
  74. docker compose logs -f web worker # follow the logs
  75. docker compose down --volumes # stop and DELETE ALL DATA
  76. ```
  77. 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`.
  78. `POSTGRES_PASSWORD` is read only when the database is first created. Changing it later means deleting the data with the last command.
  79. ## What is in the console
  80. An organization holds projects, and each project is one agent's view:
  81. | Page | What it shows |
  82. |---|---|
  83. | **Overview** | The project at a glance: activity over the last 7 or 30 days, and what needs attention. |
  84. | **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. |
  85. | **Traces** | Every run step by step, with spans, operations and logs, and two traces side by side. |
  86. | **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. |
  87. | **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. |
  88. | **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. |
  89. | **Settings** | Projects general settings, **API keys**, SDK events under **Developer**, and a danger zone. |
  90. ## Repo layout
  91. ```
  92. apps/
  93. └── web/ # @ratel/platform: the console and APIs
  94. packages/
  95. ├── brand/ # @ratel/brand: palette, fonts and logo assets
  96. ├── design-system/ # @ratel/design-system: semantic tokens and UI primitives
  97. └── sdk/ # Ratel SDK documentation; the SDK code will move here later
  98. src/ # Ratel SDK: core (Rust), sdk, adapters, rankers, telemetry
  99. scripts/ # Repository checks and release tooling
  100. docs/
  101. ├── adr/ # Architecture decision records
  102. └── assets/ # Images and other static assets
  103. ee/ # Manifest for the Enterprise modules
  104. ```
  105. The application's own layout and commands are in [apps/web/README.md](apps/web/README.md), and the layers of its core in [apps/web/lib/README.md](apps/web/lib/README.md).
  106. ## Development
  107. ### Ratel Platform
  108. Prerequisites: Node 24+ and pnpm 10.28+, with Docker for the platform's Postgres.
  109. - [apps/web/README.md](apps/web/README.md)
  110. ### Ratel SDK
  111. 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`](https://docs.astral.sh/uv/).
  112. - [packages/sdk/README.md](packages/sdk/README.md)
  113. ## Contributing
  114. - [CONTRIBUTING.md](CONTRIBUTING.md)
  115. - [AGENTS.md](AGENTS.md): for coding agents working in this repo
  116. - [SECURITY.md](SECURITY.md): how to report a vulnerability, and which versions get fixes
  117. ## License
  118. The `ratel-ai-core` engine is licensed under [Apache-2.0](LICENSE-APACHE), an explicit patent grant for the engine others embed. Everything else (the platform application, SDKs, telemetry helpers, examples) is [MIT](LICENSE.md). See [ADR-0009](docs/adr/0009-licensing.md) for the rationale.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.