## File: README.md

> Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute aggregates the **documented** free tiers of **42 provider pools / 495 models** into one honest number and shows it live on the dashboard (`/dashboard/free-tiers`).



> Animated summary of the live `/dashboard/free-tiers` page. Full methodology (pool dedupe, credit tiers, provider terms): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
>
> <sub>These figures are re-audited every two weeks against the live catalog and **move both ways** — a provider ends a free tier and the number drops; a new one lands and it climbs. We publish what the catalog actually computes, never a rounded-up best case.</sub>







## 🧩 Available

[](https://www.npmjs.com/package/omniroute)

[](https://hub.docker.com/r/diegosouzapw/omniroute)
[](LICENSE)





| **🚀 Start** | [🚀 Quick Start](#-quick-start) | [📦 Install](#-more-install-methods--docker-source-pnpm-arch) | [🆓 Zero-config](#-works-the-second-you-install-it--no-keys-no-config) |
| --- | --- | --- | --- |
| **💡 Learn** | [💥 The Promise](#-the-promise) | [🤔 Why OmniRoute](#-why-omniroute) | [🏆 What Sets Apart](#-what-sets-omniroute-apart) |
| **⚙️ Features** | [🎯 Combos](#-combos--the-flagship) | [🌐 Providers](#-343-ai-providers--90-free) | [🔌 CLI &amp; MCP](#-full-cli--a2a--mcp) |
|  | [🗜️ Compression](#%EF%B8%8F-save-1595-tokens--automatically) | [🖥️ Where It Runs](#%EF%B8%8F-where-omniroute-runs--anywhere) | [🔒 Private](#-private--local-first) |
| **👀 See it** | [🎬 In Action](#-omniroute-in-action) | [✨ What's New](#-whats-new) | [🤖 Compatible CLIs](#-compatible-clis--coding-agents) |
| **💚 Support** | [💚 Support / Donate](#-support-omniroute) | [💬 Community](#-community--help) | [💖 Sponsors](#-sponsors) |
| **📦 Project** | [🛠️ Tech Stack](#%EF%B8%8F-tech-stack) | [📖 Docs](#-documentation) | [👥 Contributors](#-500-contributors) |














```bash
# Fresh install, zero credentials — `auto` already works:
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```

<sub>Prefer a specific free backend? Call it directly, e.g. `oc/…` (OpenCode Free) or `felo/…` (Felo). Then graduate to `auto` and let OmniRoute pick.</sub>

<sub>📦 Copy-paste quickstart scripts for **Python, Node.js, PHP, and cURL** → [`examples/quickstart/`](examples/quickstart/)</sub>






















> **Want to join as an Open Source Friend?** These are the companies that back open source and help keep OmniRoute moving — and we say publicly where every token they give us goes. Reach out: [diegosouza.pw@outlook.com](mailto:diegosouza.pw@outlook.com)



| **Kimi**Moonshot AI | Thanks to **Kimi (Moonshot AI)**, our founding Open Source Friend, for backing this project! Kimi is the AI lab behind the open-weight K2 and K3 model families — **Kimi K3** delivers a 1M-token context window, native vision and frontier-level coding at a fraction of closed-model prices, and works out of the box with Claude Code, Codex and every coding tool OmniRoute serves.
      
      **What Kimi's support powers:** Kimi's API credits power OmniRoute's AI-validated release pipeline — the *merge validation powered by Kimi K3* stage that reviews every pull request before it ships — plus day-to-day feature development. First-class Kimi support ships on both rails: the direct [Kimi API](https://platform.kimi.ai?track_id=track-8197581fdd7d4139a0f562e4a03c3798&aff=omniroute) (`kimi-k3`) and the [Kimi Code coding plan](https://www.kimi.com/code?aff=omniroute) (OAuth and API key). OmniRoute is also the first Brazilian open-source project in Kimi's support program. [**Get a Kimi API key with 15% extra credits →**](https://platform.kimi.ai?track_id=track-8197581fdd7d4139a0f562e4a03c3798&aff=omniroute) |
| --- | --- |
| **Cheaper Inference**cheaperinference.com | Thanks to **Cheaper Inference**, an OmniRoute Open Source Friend, for backing this project! Cheaper Inference is a cost-ranked gateway that resells 42 frontier models — Claude, GPT-5.x, Gemini, Kimi K3, GLM, DeepSeek, Grok and MiniMax — behind one OpenAI-compatible endpoint, routing each request to the cheapest eligible provider without ever charging above the model maker's list price.
      
      **First-class support in OmniRoute:** Chat Completions, the native `/v1/responses` endpoint, vision, tool calling and 3 image models (`grok-imagine`, `nano-banana-pro`, `nano-banana-2`, reachable as `cheaperinference/&lt;model&gt;`). [**Get an API key →**](https://cheaperinference.com/?utm_source=omniroute) |



<sub>Links tagged `aff=omniroute` are partner links. They fund the project at no extra cost to you.</sub>




<sub>**🎟️ Affiliates Promo** — free signup coupons from providers we don't sponsor (click to expand)</sub>

<sub>*This section is for referral/coupon codes only. Sponsored partnerships live in **🤝 Supported by our Open Source Friends** above. OmniRoute has no sponsorship or partnership with the providers listed here — these are public coupons anyone can use.*</sub>



| **AgentRouter**agentrouter.org | **[AgentRouter](https://agentrouter.org/register?aff=70LM)** — affiliate signup · **$100 free credits** on signup (free server, expect higher latency — best for testing, not production). First-class support in OmniRoute since **v3.8.50**: Chat Completions, the Anthropic-compatible wire format and the OpenAI-compatible path. Available models include `claude-opus-4-8`, `claude-opus-5`, `gpt-5.6-sol` and more. **[Grab your $100 →](https://agentrouter.org/register?aff=70LM)**
      
      ⚠️ *Affiliate link — OmniRoute has no sponsorship or partnership with this provider.* |
| --- | --- |



<sub>Know another provider with a generous free signup coupon that benefits OmniRoute users? Open an issue and we'll add it here.</sub>









> A **combo** is a chain of models OmniRoute routes across **automatically**. Quota runs out, a provider fails, or costs spike — the combo silently slides to the next model. **This is what makes OmniRoute unbreakable.** 🛡️

### ⚡ Zero-config — just use `auto`

No combo to create. Set your model to `auto` (or a variant) and OmniRoute builds a virtual combo from your connected providers, scored live:



| Model ID | What it optimizes for |
| --- | --- |
| `auto` | 🎯 Balanced default (LKGP — sticks to your last good provider) |
| `auto/coding` | 🧑‍💻 Quality-first weights for code generation |
| `auto/fast` | ⚡ Lowest latency first |
| `auto/cheap` | 💰 Cheapest per token first |
| `auto/offline` | 🔋 Most quota / rate-limit headroom first |
| `auto/smart` | 🔭 Quality-first + 10% exploration to discover better models |



##

### 🔀 Or build your own — 19 routing strategies

All **19** strategies — mix & match per combo step:



| # | Strategy | What it does |
| --- | --- | --- |
| 1 | `priority` | First-target ordered list — drain each before the next 🥇 |
| 2 | `fill-first` | Fill each target's quota fully before moving on |
| 3 | `weighted` | Weighted random by per-target weight |
| 4 | `round-robin` | Cycle through targets in order |
| 5 | `p2c` | Power-of-two-choices random load balancing |
| 6 | `least-used` | Pick the target with the lowest current load |
| 7 | `random` | Uniform random pick (deduplicated) |
| 8 | `strict-random` | Random without de-duplicating repeats 🎲 |
| 9 | `cost-optimized` | Minimize $ per request from live catalog pricing 💸 |
| 10 | `headroom` | Pick the target with the most remaining quota |
| 11 | `reset-window` | Prefer the target whose quota window resets soonest |
| 12 | `reset-aware` | Rank by quota reset time — short windows first 📊 |
| 13 | `context-relay` | Hand off context across targets for long conversations 🧠 |
| 14 | `context-optimized` | Pick the best fit for the current context size |
| 15 | `cache-optimized` | Pin each reusable prompt prefix to the same account — maximize prompt-cache hits 🎯 |
| 16 | `lkgp` | Last-Known-Good Path — sticky to the last successful target |
| 17 | `auto` | 14-factor live scoring across every connection 🤖 |
| 18 | `fusion` | Fan out to a panel of models + a judge synthesizes one answer 🧬 |
| 19 | `pipeline` | Chain steps — each target's output feeds the next one 🔗 |



<sub>The Auto-Combo engine scores every candidate on **14 factors** (health, quota, cost, latency, success rate, freshness…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).</sub>

##

### 🧱 Resilience is built in (3 independent layers)



<sub>📖 [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)</sub>







<sub>📊 Full methodology &amp; per-feature detail vs 9router, OpenRouter, CLIProxyAPI &amp; LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)</sub>



## 💚 Support OmniRoute

OmniRoute is MIT-licensed and maintained in the open. If it saves you time or money, here's how to keep it independent — pick whatever fits you. Sponsorship never affects routing priority; it buys visibility, not ranking.



| ⭐ **Star the repo** | Free — genuinely helps visibility | [Star OmniRoute](https://github.com/diegosouzapw/OmniRoute) |
| --- | --- | --- |
| 🐙 **GitHub Sponsors** | One-off or monthly · zero platform fee | [github.com/sponsors/diegosouzapw](https://github.com/sponsors/diegosouzapw) |
| ☕ **Ko-fi** | Quick one-off tip, no signup for the donor | [ko-fi.com/diegosouzapw](https://ko-fi.com/diegosouzapw) |
| 🧋 **Buy Me a Coffee** | Small, informal gesture | [buymeacoffee.com/diegosouzapw](https://www.buymeacoffee.com/diegosouzapw) |
| 🖐 **Liberapay** | Recurring · non-profit · open source | [liberapay.com/diegosouzapw](https://liberapay.com/diegosouzapw) |
| 🇧🇷 **PIX** (Brazil) | Instant, no fees | key &amp; QR below |
| ₿ **Crypto** | BTC · ETH · USDT-TRC20 · USDC-Solana | addresses below |



**🇧🇷 PIX** — instant, no fees (Brazil)



Key (random): `5d865059-bc44-483a-962d-43ceb80126eb`

Pix copia-e-cola:

```
00020101021126580014br.gov.bcb.pix01365d865059-bc44-483a-962d-43ceb80126eb5204000053039865802BR5922OMNIROUTE CONTRIBUICAO6006BRASIL62070503***630475DD
```




**₿ Crypto** — BTC · ETH · USDT-TRC20 · USDC-Solana (click to expand)



| **₿ BTC** | Bitcoin (SegWit) | `bc1qh00smz004sy85wyl28v77tenkt3ckl6eaep7fd` |
| --- | --- | --- |
| **Ξ ETH** | Ethereum (ERC20) | `0x64Cf6B68A6Ff34288e89172950a2d00102337a84` |
| **₮ USDT** | Tron (TRC20) | `TKAF41JpuQrHbKTnsQa9svJE2T192Hvsc2` |
| **$ USDC** | Solana | `2emNNZzVVWQc3FQ2wk9M6qXUQmW8AKdjjL174fXR28Tu` |



<sub>⚠️ Send each coin only on the network shown — sending on the wrong network can lose the funds.</sub>



🐛 Found a bug or have feedback? Open a [Discussion](https://github.com/diegosouzapw/OmniRoute/discussions).



**Developer notes:** The project may generate a local `.env` file during npm install/postinstall for developer convenience. This file is intentionally ignored via `.gitignore` (see `.gitignore`) and must never be committed — if accidentally committed, rotate any exposed secrets and remove the file from history. See [docs/DEVELOPER-ENVIRONMENT.md](docs/DEVELOPER-ENVIRONMENT.md) for guidance on managing local environment files and secrets.

## 📡 OmniRoute Radar

The main free-tier headline remains **~1.53B tokens/month** from the documented,
pool-deduplicated catalog above. Temporary provider signup credits can separately lift the first
month to **~2.15B**. Radar is an optional, signed catalog overlay for people who want fresher
free-model availability between OmniRoute releases; the community catalog and every existing free
feature remain free.

Supporters can receive the live catalog and additional provider opportunities. Its separate,
mutable ceiling is **approximately 3B tokens/month at most**, depending on provider availability.
That ceiling is not a guarantee: providers can change quotas, eligibility, models, or regions at
any time.

Radar is opt-in and GET-only. The OmniRoute client does not upload prompts, traffic, provider
configuration, usage telemetry, or local announcement-dismiss state. Learn about eligibility and
the current catalog at **[radar.omniroute.online/planos](https://radar.omniroute.online/planos)**.





> Recent highlights from **v3.8.20 → v3.8.50**. Full history in [`CHANGELOG.md`](CHANGELOG.md).

- **🎛️ OmniConductor** — inbound A2A delegation to your agent fleet, Conductor skills on the Agent Card, and a dashboard panel with Faro push-to-talk voice chat. → [A2A Server](docs/frameworks/A2A-SERVER.md)
- **🛂 Adaptive admission & overload protection** — heavyweight chat requests queue instead of 503ing, with atomic RPM rolling leases per connection. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)
- **🗂️ Canonical `/v1/models` ordering** — one contiguous provider-grouped block per provider (combos pinned first), stable across every catalog source. → [API Reference](docs/reference/API_REFERENCE.md)
- **🗜️ Compression hardening** — default-on inflation guard, Caveman packs for DE / FR / JA + Chinese (wényán), RTK filters for Gradle & .NET. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
- **💸 Honest flat-rate cost** — subscription / coding-plan providers read **$0** in cost analytics; budget, quota & routing keep estimating. → [API Reference](docs/reference/API_REFERENCE.md)
- **⚖️ Quota-Share routing** — split a shared account's quota fairly across pooled keys, work-conserving so idle slices are lent out. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)
- **🤖 One-command CLI/agent setup** — `setup-*` configures 12+ coding tools; `omniroute run` launches 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI) with zero config written; `omniroute configure` is an interactive provider+model picker with per-context favorites. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)
- **🛰️ Remote mode** — drive a remote OmniRoute with scoped tokens (`connect` / `contexts` / `tokens`) + an `antigravity` OAuth helper for VPS installs. → [Remote Mode](docs/guides/REMOTE-MODE.md)
- **🧭 Smarter auto-routing** — `auto/<category>:<tier>` combos, **Fusion** (model panel + judge), task-aware routing, per-request model / mode / USD-budget overrides. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **🗜️ Pluggable compression** — 12 composable engines + Compression Studios: LLMLingua-2, two-tier Ultra, omniglyph, per-step fidelity gate, GCF v3.2, drag-reorder editor. → [Compression](docs/compression/COMPRESSION_ENGINES.md)
- **🕵️ Transparent MITM decrypt (TPROXY)** — capture CLIs that ignore proxy env vars, with a per-SNI CA + trust-store installer. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md)
- **💸 Cost telemetry everywhere** — `X-OmniRoute-*` cost/usage headers on every endpoint, cache-HIT savings header, per-key USD spend quotas. → [API Reference](docs/reference/API_REFERENCE.md)
- **🧠 Memory you control** — off by default, opt-in int8 vector quantization + typed decay, per-request `x-omniroute-no-memory`. → [Memory](docs/frameworks/MEMORY.md)
- **🛡️ Security** — prompt-injection guard on every LLM route (red-team suite), opt-in credential-masking guardrail (redacts leaked API keys/secrets in both directions), free DuckDuckGo last-resort web search, and an optional OIDC login gate for the dashboard (password login always stays available). → [Guardrails](docs/security/GUARDRAILS.md)
- **🖼️ New endpoints** — `/v1/ocr` (Mistral OCR) and `/v1/audio/translations` (Whisper-style) round out the media surface. → [API Reference](docs/reference/API_REFERENCE.md)
- **🎨 Image / video / audio generation** — one API for media: xAI Grok Imagine & Novita AI video, ComfyUI, Freepik, Adobe Firefly, Microsoft Designer, Segmind, EdgeTTS. → [API Reference](docs/reference/API_REFERENCE.md)
- **🌍 Deployment & ops** — reverse-proxy `basePath`, browser-language auto-detect, per-key device tracking, root-less MITM trust, zh-TW localization. → [Environment](docs/reference/ENVIRONMENT.md)
- **🤝 More providers & agents** — Cursor Cloud Agent, Grok Build (xAI) with browser + OAuth login, Ollama first-class card, Claude Opus 5 & Sonnet 5, Kimi official partnership (Code/Web/Moonshot), Zed, Requesty, SenseNova, Yuanbao, Agnes AI… and a refreshed **343-provider catalog**. → [Providers](docs/reference/PROVIDER_REFERENCE.md)
- **📡 Routing transparency** — every response carries an `X-OmniRoute-Decision` header naming the strategy/provider/latency that served it, a new `cache-optimized` combo strategy + Auto-Combo `cacheAffinity` factor route repeat requests back to the connection holding the cached prefix, and a read-only `/v1/auto-combo/{channel}/candidates` endpoint exposes an `auto/*` channel's live candidate pool. → [Auto-Combo](docs/routing/AUTO-COMBO.md)
- **⚡ Local performance & infra** — one-click local Redis, Cloudflare Workers / Deno Deploy relay deployers, Bifrost & Mux as supervised embedded services. → [Embedded Services](docs/frameworks/EMBEDDED-SERVICES.md)







<sub>📖 Per-tool setup for all 34 tools (26 CLI Code's + 8 CLI Agents) → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 OpenCode plugin → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)</sub>





**Launch any supported CLI through OmniRoute in one command** — no config files written,
credentials injected per process, Qwen/Gemini get a throwaway isolated home:

```bash
omniroute run claude   --model openai/gpt-5.4          # Claude Code
omniroute run codex    --model glm/glm-5.2             # OpenAI Codex CLI
omniroute run aider    --model glm/glm-5.2 -- --message "reply OK"
omniroute run goose    --model glm/glm-5.2
omniroute run opencode --model glm/glm-5.2 -- run "reply OK"
omniroute run qwen     --model glm/glm-5.2 -- -p "reply OK"
omniroute run gemini   --model glm/glm-5.2 -- --skip-trust -p "reply OK"

# Or pick provider+model interactively and write the tool's own config:
omniroute configure codex          # also: claude opencode qwen aider goose cline continue kilo
```

Every command honors the active remote context (`omniroute connect <host>`), `--dry-run`
previews the exact env/args without executing, and `--api-key-env NAME` keeps secrets out
of your shell history. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md)





> The most complete catalog of any open-source router: **343 providers**, **90+ with a free tier**, **56 free forever**.





> Same app, your machine, your rules. From a global npm install to **your phone** via Termux.



| Platform | Install | Highlights |
| --- | --- | --- |
| 📦 **npm (global)** | `npm install omniroute` | One command, any OS |
| 🐳 **Docker** | `docker run … diegosouzapw/omniroute` | Multi-arch **AMD64 + ARM64** |
| 🖥️ **Desktop (Electron)** | `npm run electron:build` | Native window + system tray — **Windows / macOS / Linux** |
| 💪 **ARM** | native `arm64` | Raspberry Pi, ARM servers, Apple Silicon |
| 📱 **Android (Termux)** | `pkg install nodejs && npx -y omniroute` | Runs **on your phone**, 24/7, no root |
| 📲 **PWA** | "Add to Home Screen" | Fullscreen, offline, installable from browser |
| 🧩 **OpenCode plugin** | `@omniroute/opencode-provider` | Native OpenCode integration |
| 🤖 **VS Code Copilot Chat** | install **OmniCopilot** extension | Every OmniRoute model in the native Copilot Chat picker — stable &amp; Insiders |
| 🛠️ **From source** | `npm install && npm run dev` | Hack on it, contribute |



<sub>📖 [Docker Guide](docs/guides/DOCKER_GUIDE.md) · [Desktop](electron/README.md) · [Termux](docs/guides/TERMUX_GUIDE.md) · [PWA](docs/guides/PWA_GUIDE.md) · [OpenCode](docs/frameworks/OPENCODE.md)</sub>





> No new sidebar, no new chat UI — every model OmniRoute serves shows up right in the
> **Copilot Chat model picker you already use**. Since VS Code 1.122, provider models work
> without a GitHub sign-in or a Copilot subscription — agent mode, tool calling and vision, for
> free.

Install the **[OmniCopilot](https://github.com/diegosouzapw/OmniCopilot)** extension, point it
at your OmniRoute server (defaults to `localhost:20128`), then open Copilot Chat → model picker
→ **Manage Models…** → **OmniRoute**.



| Store | Link | Works with |
| --- | --- | --- |
| 🧩 **VS Code Marketplace** | [Install →](https://marketplace.visualstudio.com/items?itemName=diegosouzapw.omnicopilot) | VS Code — stable &amp; Insiders |
| 🔓 **Open VSX Registry** | [Install →](https://open-vsx.org/extension/diegosouzapw/omnicopilot) | Cursor, Windsurf, VSCodium, Theia, code-server, Gitpod, Antigravity, Kiro… |



From inside the editor: open the **Extensions** view, search **"OmniRoute"**, click **Install**
— works the same way on both stores. Source, issues and the publishing runbook live at
[diegosouzapw/OmniCopilot](https://github.com/diegosouzapw/OmniCopilot).

<sub>📖 [VS Code Copilot Chat guide](docs/guides/VSCODE-COPILOT.md) — setup, what the picker shows, dashboard-in-a-tab, troubleshooting</sub>







<sub>📖 [Authorization](docs/architecture/AUTHZ_GUIDE.md) · [Guardrails](docs/security/GUARDRAILS.md) · [Compliance](docs/security/COMPLIANCE.md)</sub>





> Beyond the server, OmniRoute is a **full command-line cockpit** with **80+ commands**, plus open agent protocols so an AI agent can drive it **on its own**.

### ⌨️ A real CLI (not just `start`)

```bash
omniroute               # serve gateway + dashboard (port 20128)
omniroute chat          # interactive TUI chat client (slash: /model /combo /skill /memory)
omniroute setup         # guided first-run wizard
omniroute doctor        # diagnose providers, ports, native deps
```

### 🛰️ Remote mode — run the CLI here, OmniRoute on a VPS

OmniRoute on a server? Drive it from your laptop with the **same CLI**. Log in once
with a scoped access token; every command then targets the remote.

```bash
omniroute connect 192.168.0.15            # password → scoped token, saved as a context
omniroute models list                     # ← runs against the REMOTE server
omniroute configure codex                 # ← picks a remote model, writes a local Codex profile
omniroute tokens create --name ci --scope read   # mint narrower tokens for other machines
omniroute contexts use default            # ← switch back to the local server
```

Tokens are scoped `read` / `write` / `admin`; process-spawning routes stay loopback-only.
<sub>📖 [Remote Mode](docs/guides/REMOTE-MODE.md)</sub>







### 🤝 Connect an agent — and it controls OmniRoute itself

Expose OmniRoute over **MCP**, **A2A**, a **REST API**, **webhooks** or a **remote CLI** — any capable agent (or your own code) gets the keys to the whole gateway: routing, providers, combos, cache, compression, memory — autonomously. HTTP endpoints below are served under `http://localhost:20128`.



| Interface | Endpoint / command | Use it for |
| --- | --- | --- |
| 🧰 **MCP (stdio)** | `omniroute --mcp` | Plug into Claude Desktop, Cursor, any MCP client |
| 🌊 **MCP (HTTP)** | `/api/mcp/stream` | Remote MCP — **109 tools**, 33 scopes, full audit trail |
| 📡 **MCP (SSE)** | `/api/mcp/sse` | Streaming MCP transport |
| 🤝 **A2A** | `/.well-known/agent.json` | Agent-to-agent, **JSON-RPC 2.0** + SSE, 6 skills |
| 🌐 **REST API** | `/v1/*` | OpenAI-compatible — chat, embeddings, images, audio, OCR |
| 🔔 **Webhooks** | `/api/webhooks` | Push events (usage, quota, errors, routing) to your URL |
| 🛰️ **Remote CLI** | `omniroute connect ` | Drive a remote instance with scoped access tokens |



```bash
# Give Claude Code the full OmniRoute toolset over MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream
```

<sub>📖 [MCP Server](docs/frameworks/MCP-SERVER.md) · [A2A Server](docs/frameworks/A2A-SERVER.md) · [Agent Protocols](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)</sub>





### 📖 How it works — pipeline, architecture & savings math



Default stacked combo runs `RTK → Caveman`. When both act on the same tool/context payload, savings compound:

```txt
combined = 1 − (1 − RTK) × (1 − Caveman_input)
average  = 1 − (1 − 0.80) × (1 − 0.46) = 89.2%
range    = 78.4 – 94.6%
```

Code blocks, URLs, JSON and structured data are **always protected** by the preservation engine.

> **Why use many tokens when few tokens do the trick?** Every request passes through OmniRoute's compression pipeline **transparently** — no client changes. It's now a **stack of 12 composable engines** that run in order and mix & match per routing combo — building on ideas from [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 90K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua), and [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR).

### 🧱 The 12-engine stack

Engines run in pipeline order; each is independently toggleable and configurable per combo:



| # | Engine | What it does |
| --- | --- | --- |
| 1 | **Session-Dedup** | Drops content repeated across turns (content-addressed, cross-turn) |
| 2 | **CCR** | Archives large blocks behind retrieve markers, fetched on demand |
| 3 | **Lite** | Whitespace + image-URL trimming (latency-light baseline) |
| 4 | **RTK** | Smart tool-result filtering, dedup & truncation (command-aware) |
| 5 | **Responses Tool Output** | Lossless-first JSON + bounded diagnostic compression for shell/patch/search/build outputs (Responses API) |
| 6 | **Headroom** | Lossless tabular compaction of JSON arrays (~30%) via a vendored **GCF** codec |
| 7 | **Relevance** | Extractive sentence scoring against the last user query |
| 8 | **Caveman** | Rule-based prose compression (~65–75% on output) |
| 9 | **Aggressive** | Summarization + progressive aging of old turns |
| 10 | **LLMLingua-2** | ML semantic pruning via MobileBERT ONNX — code-safe, async |
| 11 | **Ultra** | Heuristic token pruning with an optional small-model (SLM) tier |
| 12 | **OmniGlyph** | Experimental context-as-image encoding for measured Claude Fable 5 on the direct Anthropic wire; GPT 5.6 transformers remain fail-closed pending provider receipts. Four compression profiles (aggressive default, balanced, coding-safe, passthrough) (most aggressive; opt-in) |



Code blocks, URLs and structured data are **always preserved** byte-perfect. **One-click presets** combine the engines:



| Mode | Savings | Best for |
| --- | --- | --- |
| 🪶 **Lite** | ~15% | Always-on safe default |
| 🪨 **Standard (Caveman)** | ~30% | Daily coding |
| ⚡ **Aggressive** | ~50% | Long tool-heavy sessions |
| 🔥 **Ultra** | ~75% | Maximum savings |
| 🧰 **RTK** | 60–90% | Shell/test/build/git output |
| 🔗 **Stacked (RTK → Caveman)** | **78–95%** | Mixed prompts + tool logs |



**Real example — Standard mode:**

> **Before (69 tokens):** _"The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."_
>
> **After (19 tokens):** _"New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."_
>
> **Same answer. 72% fewer tokens. Zero accuracy loss.** ✅

**PT-BR example — [Troglodita](https://github.com/leninejunior/troglodita) mode:**

> **Antes (42 tokens):** _"O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."_
>
> **Depois (12 tokens):** _"Re-render: ref nova cada ciclo (objeto inline recriado). Usar `useMemo`."_
>
> **Mesma resposta. ~70% menos tokens. Precisão técnica intacta.** ✅



### 🎚️ Beyond the engines — output styles, the adaptive dial & per-request control

The 12 engines above shrink what goes **in**. Three more layers shape **how**, **when**, and what comes **out**:

- **🪄 Output Styles** _(output-axis steering)_ — inject deterministic, cache-safe response-shaping instructions; combinable, each at `lite` / `full` / `ultra` intensity. Adding a style is a one-line registry entry:
  - **Terse prose** — drop filler / articles / hedging; keep technical substance exact.
  - **Less code** — "lazy senior dev" YAGNI: smallest working change, no unrequested scaffolding.
  - **Terse CJK (文言)** — classical-Chinese ultra-terse style (locale-gated to `zh`).
- **🎯 Adaptive context-budget** _(the dial)_ — instead of one on/off token threshold, escalate the cheapest, most-lossless engines only as far as needed to **fit the model's context window**. Policy: `reserve-output` (default, model-aware) · `percentage` · `absolute`. Mode: `floor` (guarantee fit) · `replace-autotrigger` (your explicit choice wins) · `off` (legacy threshold).
- **🎛️ Where compression is decided** _(precedence, high → low)_ — per-request `x-omniroute-compression` header › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in the `X-OmniRoute-Compression: <mode>; source=` response header.

Auto-trigger by token threshold, flip on the adaptive dial, pin a named profile, set a one-off per request, or assign a pipeline per routing combo — whichever fits the workload. An opt-in offline **eval harness** (`npm run eval:compression`) scores fidelity vs. savings on a pinned corpus before you promote a change.

📖 [`COMPRESSION_GUIDE.md`](docs/compression/COMPRESSION_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/compression/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/compression/COMPRESSION_ENGINES.md)





**1) Install & run**

```bash
npm install omniroute
omniroute
```

> 💡 See `npm warn ERESOLVE` or peer-dep warnings? [They're harmless](docs/guides/TROUBLESHOOTING.md#npm-install-warnings-eresolve--peer--deprecated).

Dashboard at `http://localhost:20128` · API at `http://localhost:20128/v1`.

**2) Connect a FREE provider (no signup)**

Dashboard → **Providers** → connect **Kiro AI** (free Claude, ~50 credits/month per account) or **OpenCode Free** (no auth) → done.

**3) Point your coding tool**

```txt
Base URL: http://localhost:20128/v1
API Key:  [copy from Dashboard → Endpoints]
Model:    auto            (zero-config smart routing — or any provider/model)
```

**4) Verify it's working**

```bash
curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
```

You should see your connected models listed. 🎉 That's it — start coding, and OmniRoute auto-routes & falls back for you.

If your client cannot send custom headers, OmniRoute also exposes tokenized compatibility aliases:

```txt
OpenAI catalog:   http://localhost:20128/vscode/YOUR_KEY/
OpenAI models:    http://localhost:20128/vscode/YOUR_KEY/models
OpenAI chat:      http://localhost:20128/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
Ollama chat:      http://localhost:20128/vscode/YOUR_KEY/api/chat
Ollama tags:      http://localhost:20128/vscode/YOUR_KEY/api/tags
```

Use these only for clients that cannot attach `Authorization: Bearer ...`. Header auth remains the preferred mode.



## 📦 More install methods — Docker, source, pnpm, Arch

**🐳 Docker**

```bash
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```

`:latest` follows the highest **published** stable SemVer. It does not track git `main`. Pin `:X.Y.Z` for GitOps. See [Docker Release Channels](docs/guides/DOCKER_GUIDE.md#release-channels).

> **Pre-release Docker channel:** `diegosouzapw/omniroute:next` and
> `diegosouzapw/omniroute:next-web` follow the current default `release/v*`
> branch. These mutable tags are intended only for testing unreleased fixes and
> are **not supported for production**. See
> [Docker Release Channels](docs/guides/DOCKER_GUIDE.md#release-channels).

**🛠️ From source**

```bash
cp .env.example .env && npm install
PORT=20128 npm run dev
```

**📦 pnpm**

```bash
pnpm add omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute
```

**🐧 Arch Linux (AUR)**

```bash
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
```

**🔧 Nix (Flake)**

```bash
# Using Nix flakes
nix develop
npm run dev

# Or using devbox
devbox run npm run dev
```

📖 [Docker Guide](docs/guides/DOCKER_GUIDE.md) — Compose profiles, Caddy HTTPS, Cloudflare tunnels.

**🦭 Podman**

```bash
# 1. Prepare the bind-mounted data directory
mkdir -p data

# 2. Linux + local rootless Podman only (never a remote Podman Machine client):
podman unshare chown 1000:1000 ./data

# 3. Set the runtime hint, build the local Compose image, and start
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build
```

On macOS or Windows, Podman uses a remote Podman Machine: skip `podman unshare` and
follow the [topology-specific data directory guidance](contrib/podman/README.md#data-directory-permissions-by-topology).

📖 [Podman Guide](contrib/podman/README.md) — Compose builds, Podman Machine, and
Linux/systemd Quadlet setup.

**⚡ Faster / leaner install (skip the native build)**

The native SQLite engine (`better-sqlite3`) is an **optional** dependency, so a global
install never blocks on compiling from source: it uses a prebuilt binary when one matches
your platform/Node, and otherwise falls back transparently to a pure-JS engine
(`node:sqlite` on Node 22+, else the bundled `sql.js` WASM) — no build tools required.

To skip the post-install native warm-up entirely (CI, headless, or slow machines):

```bash
OMNIROUTE_SKIP_POSTINSTALL=1 npm install omniroute   # CI=1 also skips it
```

For the fastest installs prefer **pnpm** (content-addressed store + hard links — see above).
For a dashboard-free, headless runtime use the Docker `base` profile (above) or the
[Termux guide](docs/guides/TERMUX_GUIDE.md). The CLI and the web dashboard are served by the
same process on one port, so there is no separate CLI-only package today.





## 📹 Video Guides



**Ranking completo (`v > 0`, maior alcance):**

| #1                                                                                     | #2                                                                                                      | #3                                                                                     | #4                                                                                          | #5                                                                                          |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [nick_saraev — Instagram](https://www.instagram.com/reel/Da8ZthUPK98/) — **1,628,910** | [milesreevesai — TikTok](https://www.tiktok.com/@milesreevesai/video/7667980059189366019) — **620,400** | [Vaibhav Sisinty — YouTube](https://www.youtube.com/watch?v=QucgvbO5gsM) — **373,084** | [Nick Automates — YouTube Shorts](https://www.youtube.com/shorts/fZIBK_4fKq8) — **207,714** | [midudev — TikTok](https://www.tiktok.com/@midudev/video/7664636453544152342) — **177,800** |

| #6                                                                                    | #7                                                                                                  | #8                                                                                  | #9                                                                           | #10                                                                                    |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [theopenstack — Instagram](https://www.instagram.com/reel/DaSs65mMrHk/) — **155,453** | [t.ghoush.ai — TikTok](https://www.tiktok.com/@t.ghoush.ai/video/7669497680527248656) — **152,800** | [Valency Labs — YouTube](https://www.youtube.com/watch?v=LkP6ocAoQkk) — **135,974** | [Asati — YouTube](https://www.youtube.com/watch?v=JjPtJcqwhqg) — **126,130** | [Vaibhav Sisinty — YouTube](https://www.youtube.com/watch?v=NuNDpeZYQ28) — **122,672** |

Métricas de validação: 1002 vídeos rastreados · 7,069,190 visualizações conhecidas · 595 perfis/canais · 13+ idiomas · 13+ criadores.

> 🎬 **Made a video about OmniRoute?** Open an [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) or [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) with the link — we'll feature it here.





---






| Layer | Technology |
| --- | --- |
| **Runtime** | Node.js 22.x / 24.x LTS — `&gt;=22.22.2 &lt;23    &gt;=24.0.0 &lt;27` |
| **Language** | TypeScript 6.0 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core since v2.0) |
| **Framework** | Next.js 16 + React 19 + Tailwind CSS 4 |
| **Database** | better-sqlite3 (SQLite, WAL journaling) + LowDB (JSON legacy) — 120 domain modules, 154 migrations |
| **Memory** | SQLite FTS5 full-text + int8-quantized vector embeddings, typed decay |
| **Schemas** | Zod 4 — MCP tool I/O validation + API contracts |
| **Protocols** | MCP (stdio / HTTP / SSE) + A2A v0.3 (JSON-RPC 2.0 + SSE) |
| **Streaming** | Server-Sent Events (SSE) + WebSocket bridge (`/v1/ws`) |
| **Compression** | 12-engine pipeline — RTK, Caveman, LLMLingua-2 (MobileBERT ONNX), GCF, OmniGlyph |
| **Auth &amp; security** | OAuth 2.0 (PKCE) + JWT + API Keys + MCP scoped auth · AES-256-GCM at rest · DOMPurify |
| **Stealth** | wreq-js — JA3 / JA4 TLS fingerprint impersonation, 3-level proxy |
| **Resilience** | Circuit breaker, exponential backoff, anti-thundering-herd, auto-combo self-healing |
| **Logging** | pino — structured JSON logs with request context |
| **Testing** | Node.js test runner + Vitest — **25,000+ test cases** across 3,300+ files (unit, integration, E2E, security, ecosystem) |
| **Platforms** | Desktop (Electron) · Android (Termux) · PWA (any browser) |
| **CI/CD** | GitHub Actions — auto npm publish + Docker Hub on release |
| **Links** | [Website](https://omniroute.online) · [npm](https://www.npmjs.com/package/omniroute) · [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) |





### 📘 Getting Started



| Document | Description |
| --- | --- |
| **[User Guide](docs/guides/USER_GUIDE.md)** | Providers, combos, CLI integration, deployment |
| **[Setup Guide](docs/guides/SETUP_GUIDE.md)** | Full install methods, CLI tool configs, protocol setup, timeout tuning |
| **[CLI Tools Guide](docs/reference/CLI-TOOLS.md)** | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot |
| **[Remote Mode](docs/guides/REMOTE-MODE.md)** | Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens |
| **[Claude Code Config](docs/guides/CLAUDE-CODE-CONFIGURATION.md)** | Point Claude Code at OmniRoute (local/remote) with `launch` + per-model profiles |
| **[Quick Start](README.md#-quick-start)** | 3-step install → connect → configure |



### 🔧 Operations & Deployment



| Document | Description |
| --- | --- |
| **[Docker Guide](docs/guides/DOCKER_GUIDE.md)** | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |
| **[Podman Guide](contrib/podman/README.md)** | Quadlet systemd integration, podman-compose, SELinux |
| **[VM Deployment](docs/ops/VM_DEPLOYMENT_GUIDE.md)** | Complete guide: VM + nginx + Cloudflare setup |
| **[Fly.io Deployment](docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md)** | Deploy to Fly.io with persistent storage |
| **[Termux Guide](docs/guides/TERMUX_GUIDE.md)** | Run OmniRoute on Android via Termux |
| **[PWA Guide](docs/guides/PWA_GUIDE.md)** | Progressive Web App install, caching, architecture |
| **[Uninstall Guide](docs/guides/UNINSTALL.md)** | Clean removal for all install methods |
| **[Environment Config](docs/reference/ENVIRONMENT.md)** | Complete `.env` variables and references |



### 🧠 Features & Architecture



| Document | Description |
| --- | --- |
| **[Architecture](docs/architecture/ARCHITECTURE.md)** | System architecture, data flow, and internals |
| **[Compression Guide](docs/compression/COMPRESSION_GUIDE.md)** | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked |
| **[RTK Compression](docs/compression/RTK_COMPRESSION.md)** | Command-output compression, filters, trust, verify, raw-output recovery |
| **[Compression Engines](docs/compression/COMPRESSION_ENGINES.md)** | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces |
| **[Compression Rules Format](docs/compression/COMPRESSION_RULES_FORMAT.md)** | JSON rule-pack schemas for Caveman and RTK filters |
| **[Compression Language Packs](docs/compression/COMPRESSION_LANGUAGE_PACKS.md)** | Language detection and Caveman rule-pack authoring |
| **[Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)** | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing |
| **[Auto-Combo Engine](docs/routing/AUTO-COMBO.md)** | 14-factor scoring, mode packs, self-healing |
| **[Proxy Guide](docs/ops/PROXY_GUIDE.md)** | 3-level proxy system, 1proxy marketplace, registry CRUD |
| **[Free Tiers](docs/reference/FREE_TIERS.md)** | 90+ free providers consolidated directory (42 documented token pools / 495 models) |
| **[Features Gallery](docs/guides/FEATURES.md)** | Visual dashboard tour with screenshots |
| **[Codebase Documentation](docs/architecture/CODEBASE_DOCUMENTATION.md)** | Beginner-friendly codebase walkthrough |



### 🤖 Protocols & APIs



| Document | Description |
| --- | --- |
| **[API Reference](docs/reference/API_REFERENCE.md)** | All endpoints with examples |
| **[OpenAPI Spec](docs/openapi.yaml)** | OpenAPI 3.0 specification |
| **[MCP Server](open-sse/mcp-server/README.md)** | 109 MCP tools, IDE configs, Python/TS/Go clients |
| **[MCP Server Guide](docs/frameworks/MCP-SERVER.md)** | MCP installation, transports, and tool reference |
| **[A2A Server](src/lib/a2a/README.md)** | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
| **[A2A Server Guide](docs/frameworks/A2A-SERVER.md)** | A2A agent card, tasks, skills, and streaming |



### 📋 Project & Quality



| Document | Description |
| --- | --- |
| **[Contributing](CONTRIBUTING.md)** | Development setup and guidelines |
| **[Branching & Release Model](docs/ops/BRANCHING_MODEL.md)** | Where PRs target (`release/*`), what `main` and tags mean |
| **[Changelog](CHANGELOG.md)** | Full per-version release history |
| **[Security Policy](SECURITY.md)** | Vulnerability reporting and security practices |
| **[i18n Guide](docs/guides/I18N.md)** | 43-language support, translation workflow, RTL |
| **[Release Checklist](docs/ops/RELEASE_CHECKLIST.md)** | Pre-release validation steps |
| **[Coverage Plan](docs/ops/COVERAGE_PLAN.md)** | Test coverage strategy and 25,000+ test suite |







---



## 💖 Sponsors







[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)

### How to Contribute

1. Fork the repository
2. Branch from the **active** `release/vX.Y.Z` tip (not `main`) — see [Branching & Release Model](docs/ops/BRANCHING_MODEL.md)
3. Create your feature branch (`git checkout -b feat/amazing-feature`)
4. Commit your changes (`git commit -m 'feat: add amazing feature'`)
5. Push to the branch (`git push origin feat/amazing-feature`)
6. Open a Pull Request with **base = that `release/vX.Y.Z` branch**

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

### Releasing a New Version

```bash
# Create a release — npm publish happens automatically
gh release create v3.8.2 --title "v3.8.2" --generate-notes
```









OmniRoute stands on the shoulders of giants. It started as a fork of **[9router](https://github.com/decolua/9router)** and a TypeScript port of the Go project **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — and from there, every subsystem below was inspired by an open-source project that got there first. Each one shaped a concrete piece of OmniRoute. This is our thank-you to all of them. 🙏

> ⭐ star counts as of July 2026 — go give these projects a star.

### 🧬 Lineage & gateway



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |
| **[9router](https://github.com/decolua/9router)** | 22.7k | The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite. |
| **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** | 43.6k | The Go implementation that inspired this JavaScript / TypeScript port. |
| **[LiteLLM](https://github.com/BerriAI/litellm)** | 54.0k | The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing. |



### 🗜️ Context & token compression — engines



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |
| **[Caveman](https://github.com/JuliusBrussee/caveman)** | 90.8k | The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules. |
| **[RTK – Rust Token Killer](https://github.com/rtk-ai/rtk)** | 71.8k | High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline. |
| **[headroom](https://github.com/headroomlabs-ai/headroom)** | 60.1k | Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern. |
| **[LLMLingua](https://github.com/microsoft/LLMLingua)** | 6.5k | Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open `llmlingua` engine. |
| **[llmlingua-2-js](https://github.com/atjsh/llmlingua-2-js)** | 30 | The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine. |
| **[Troglodita](https://github.com/leninejunior/troglodita)** | 26 | PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar. |
| **[ponytail](https://github.com/DietrichGebert/ponytail)** | 86.0k | The viral "lazy senior dev" YAGNI-coder skill — inspired our **less-code** Output Style: smallest-working-change steering that cuts _generated_ code (the output-axis sibling to Caveman's terse prose). |



### 🧩 Compact formats, token research & code-aware tooling



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |
| **[TOON](https://github.com/toon-format/toon)** | 24.9k | Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage. |
| **[GCF – Graph Compact Format](https://github.com/blackwell-systems/gcf)** | 22 | First inspired our tabular compaction stage; now its zero-dependency, lossless generic-profile encoder is **vendored directly** as the Headroom codec (MIT, SPDX-marked), current with GCF spec v3.2. |
| **[token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)** | 444 | Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine. |
| **[token-savior](https://github.com/Mibayy/token-savior)** | 1.1k | Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction. |
| **[token-saver](https://github.com/ppgranger/token-saver)** | 117 | Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip. |
| **[token-optimizer](https://github.com/alexgreensh/token-optimizer)** | 1.7k | "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking. |
| **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** | 16 | A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design. |
| **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** | 3 | Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our `headroom`/`ccr`/`session-dedup` engine design and the cache-stable "compressed form is position-independent" invariant. |
| **[mcp-compressor](https://github.com/atlassian-labs/mcp-compressor)** | 98 | MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction. |
| **[RepoMapper](https://github.com/pdavis68/RepoMapper)** | 187 | Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration. |
| **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** | 4 | Declarative shell-output reduction over MCP — validated our declarative bash-output compaction. |
| **[ts-morph](https://github.com/dsherret/ts-morph)** | 6.1k | TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals. |



### 🧠 Memory & RAG



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |
| **[Mem0](https://github.com/mem0ai/mem0)** | 61.2k | Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture. |
| **[Letta (MemGPT)](https://github.com/letta-ai/letta)** | 23.9k | Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model. |
| **[WFGY](https://github.com/onestardao/WFGY)** | 1.8k | The ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide. |



### 🛰️ Traffic inspection, MITM & transparent proxy



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |
| **[llm-interceptor](https://github.com/chouzz/llm-interceptor)** | 49 | MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT). |
| **[ProxyBridge](https://github.com/InterceptSuite/ProxyBridge)** | 5.5k | Transparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, `/proc` process attribution and TPROXY capture. |



### 📚 Model data, observability & UI



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |
| **[models.dev](https://github.com/anomalyco/models.dev)** | 6.0k | Open database of AI model specs, pricing and capabilities — synced natively into our model catalog. |
| **[React Flow / xyflow](https://github.com/xyflow/xyflow)** | 37.7k | The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio. |
| **[LangGraph](https://github.com/langchain-ai/langgraph)** | 37.6k | LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view. |
| **[Langfuse](https://github.com/langfuse/langfuse)** | 31.4k | Its trace → span → generation observability model shaped our Compression Studio waterfall. |
| **[Kiali](https://github.com/kiali/kiali)** | 3.6k | Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio. |
| **[lobe-icons](https://github.com/lobehub/lobe-icons)** | 2.2k | AI/LLM brand logos that render the provider icons across our dashboard. |



### 🛡️ Security



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |
| **[awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)** | 710 | A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). |



### 🧭 Complementary tools



| Project | ⭐ | How it inspired OmniRoute |
| --- | --- | --- |



## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

---

## File: docs/README.md

---
title: "OmniRoute Documentation"
version: 3.8.40
lastUpdated: 2026-06-28
---

# OmniRoute Documentation

Navigable index of the OmniRoute documentation set. Topics are grouped by intent so you can find what you need quickly.

> Looking for the project overview, install steps, or release notes? See the root [README.md](../README.md), [ROADMAP.md](../ROADMAP.md), [CHANGELOG.md](../CHANGELOG.md), and [CONTRIBUTING.md](../CONTRIBUTING.md).

---

## For Non-Tech Users

Simple guides for using OmniRoute — no technical background needed.

### getting-started/

- [QUICK-START.md](getting-started/QUICK-START.md) — install and run OmniRoute in 3 minutes.
- [AUTO-COMBO-GUIDE.md](getting-started/AUTO-COMBO-GUIDE.md) — let OmniRoute pick the best AI for you.
- [PROVIDERS-GUIDE.md](getting-started/PROVIDERS-GUIDE.md) — how to connect AI providers.
- [FREE-TIERS-GUIDE.md](getting-started/FREE-TIERS-GUIDE.md) — get free AI with no credit card.
- [WEB-COOKIE-GUIDE.md](getting-started/WEB-COOKIE-GUIDE.md) — web cookie providers (session-credential setup).

### guides/

- [SETUP_GUIDE.md](guides/SETUP_GUIDE.md) — first-time setup of OmniRoute.
- [USER_GUIDE.md](guides/USER_GUIDE.md) — daily usage of the dashboard and API.
- [THINKING_BUDGET.md](guides/THINKING_BUDGET.md) — thinking/reasoning budget modes (passthrough vs auto-strip).
- [FEATURES.md](guides/FEATURES.md) — dashboard feature gallery.
- [TIERS.md](guides/TIERS.md) — OmniRoute tiers explained (user guide).
- [USAGE_QUOTA_GUIDE.md](guides/USAGE_QUOTA_GUIDE.md) — usage, quota & spend tracking.
- [COST_TRACKING.md](guides/COST_TRACKING.md) — cost and spend tracking.
- [FREE_PROVIDER_RANKINGS.md](guides/FREE_PROVIDER_RANKINGS.md) — free provider rankings (Arena ELO).
- [DOCKER_GUIDE.md](guides/DOCKER_GUIDE.md) — running OmniRoute under Docker.
- [ELECTRON_GUIDE.md](guides/ELECTRON_GUIDE.md) — desktop (Electron) builds.
- [TERMUX_GUIDE.md](guides/TERMUX_GUIDE.md) — running on Android via Termux.
- [PWA_GUIDE.md](guides/PWA_GUIDE.md) — installing the dashboard as a PWA.
- [REMOTE-MODE.md](guides/REMOTE-MODE.md) — exposing OmniRoute remotely + scoped tokens.
- [CLI-INTEGRATIONS.md](guides/CLI-INTEGRATIONS.md) — master table of `setup-*` CLI integrations.
- [CLAUDE-CODE-CONFIGURATION.md](guides/CLAUDE-CODE-CONFIGURATION.md) — Claude Code CLI with OmniRoute.
- [CODEX-CLI-CONFIGURATION.md](guides/CODEX-CLI-CONFIGURATION.md) — Codex CLI with OmniRoute.
- [KIRO_SETUP.md](guides/KIRO_SETUP.md) — Kiro setup.
- [ANTIGRAVITY-ONBOARDING.md](guides/ANTIGRAVITY-ONBOARDING.md) — Antigravity (Google One AI) onboarding.
- [MANAGEMENT-AUTH.md](guides/MANAGEMENT-AUTH.md) — management authentication.
- [I18N.md](guides/I18N.md) — translation and locale workflow.
- [TROUBLESHOOTING.md](guides/TROUBLESHOOTING.md) — detailed troubleshooting reference.
- [UNINSTALL.md](guides/UNINSTALL.md) — clean removal steps.

---

## For Tech Users

Technical documentation for developers and contributors.

## architecture/

How the system is put together — read these to understand the runtime, code layout, and resilience model.

- [ARCHITECTURE.md](architecture/ARCHITECTURE.md) — high-level system architecture (request pipeline, layers, modules).
- [CODEBASE_DOCUMENTATION.md](architecture/CODEBASE_DOCUMENTATION.md) — engineering reference for the codebase.
- [REPOSITORY_MAP.md](architecture/REPOSITORY_MAP.md) — directory-by-directory navigation guide.
- [AUTHZ_GUIDE.md](architecture/AUTHZ_GUIDE.md) — authorization pipeline (route classifier + policy engine).
- [RESILIENCE_GUIDE.md](architecture/RESILIENCE_GUIDE.md) — provider circuit breaker, connection cooldown, and model lockout.
- [QUALITY_GATES.md](architecture/QUALITY_GATES.md) — quality-gate scripts and CI jobs inventory.
- [MONITORING_SECTIONS.md](architecture/MONITORING_SECTIONS.md) — monitoring/costs dashboard navigation.
- [cluster-decisions.md](architecture/cluster-decisions.md) — optional sidecar/cluster profile decisions.
- [DESIGN_SYSTEM.md](architecture/DESIGN_SYSTEM.md) — design system & visual identity.
- [ROUTER_BACKENDS.md](architecture/ROUTER_BACKENDS.md) — router backends & embedded services architecture contract (ADR).
- [admission-lanes.md](architecture/admission-lanes.md) — the two admission-lane systems and what gates each.
- [persistence-backend-boundary.md](architecture/persistence-backend-boundary.md) — pluggable persistence boundary (ADR).

## reference/

Lookup material — API surface, environment variables, CLI flags, provider catalog.

- [API_REFERENCE.md](reference/API_REFERENCE.md) — REST API endpoints and shapes.
- [PROVIDER_REFERENCE.md](reference/PROVIDER_REFERENCE.md) — auto-generated provider catalog (do not edit by hand).
- [PROVIDER_PLUGIN_MANIFEST.md](reference/PROVIDER_PLUGIN_MANIFEST.md) — sidecar-safe provider plugin contract for Bifrost and CLIProxyAPI migration.
- [openapi.yaml](openapi.yaml) — OpenAPI spec for the public API.
- [ENVIRONMENT.md](reference/ENVIRONMENT.md) — environment variables reference.
- [FEATURE_FLAGS.md](reference/FEATURE_FLAGS.md) — feature flags and their defaults.
- [CLI-TOOLS.md](reference/CLI-TOOLS.md) — bundled CLI commands.
- [FREE_TIERS.md](reference/FREE_TIERS.md) — free-tier LLM provider directory.
- [FREE_PROXIES_API.md](reference/FREE_PROXIES_API.md) — free proxies API.
- [RELAY_BACKEND_STRATEGY.md](reference/RELAY_BACKEND_STRATEGY.md) — relay backend strategy.
- [RELAY_TROUBLESHOOTING.md](reference/RELAY_TROUBLESHOOTING.md) — relay troubleshooting.

## frameworks/

Pluggable subsystems exposed to clients, agents, and operators.

- [MCP-SERVER.md](frameworks/MCP-SERVER.md) — Model Context Protocol server.
- [A2A-SERVER.md](frameworks/A2A-SERVER.md) — Agent-to-Agent (A2A) JSON-RPC server.
- [ACP.md](frameworks/ACP.md) — Agent Client Protocol.
- [AGENT_PROTOCOLS_GUIDE.md](frameworks/AGENT_PROTOCOLS_GUIDE.md) — A2A / ACP / Cloud agent overview.
- [AGENTBRIDGE.md](frameworks/AGENTBRIDGE.md) — IDE agent bridge.
- [AGENT-SKILLS.md](frameworks/AGENT-SKILLS.md) — agent skills catalog.
- [CLOUD_AGENT.md](frameworks/CLOUD_AGENT.md) — cloud agent runtime and providers.
- [SKILLS.md](frameworks/SKILLS.md) — Skills framework (sandboxed extension).
- [MEMORY.md](frameworks/MEMORY.md) — persistent memory (FTS5 + Qdrant).
- [WEBHOOKS.md](frameworks/WEBHOOKS.md) — webhook events and dispatch.
- [EVALS.md](frameworks/EVALS.md) — eval suites.
- [GAMIFICATION.md](frameworks/GAMIFICATION.md) — gamification & leaderboard system.
- [EMBEDDED-SERVICES.md](frameworks/EMBEDDED-SERVICES.md) — embedded sidecar services (9Router, CLIProxyAPI).
- [NOTION_CONTEXT.md](frameworks/NOTION_CONTEXT.md) — Notion context source.
- [OBSIDIAN_CONTEXT.md](frameworks/OBSIDIAN_CONTEXT.md) — Obsidian context source.
- [LOCAL_CORPUS_CONTEXT.md](frameworks/LOCAL_CORPUS_CONTEXT.md) — local corpus context source (approved directory exposed to MCP).
- [OPENCODE.md](frameworks/OPENCODE.md) — OpenCode integration.
- [OPEN_SSE_ARCHITECTURE.md](frameworks/OPEN_SSE_ARCHITECTURE.md) — open-sse streaming engine internals.
- [PLAYGROUND_STUDIO.md](frameworks/PLAYGROUND_STUDIO.md) — Playground Studio UI.
- [SEARCH_TOOLS_STUDIO.md](frameworks/SEARCH_TOOLS_STUDIO.md) — Search Tools Studio UI.
- [TRAFFIC_INSPECTOR.md](frameworks/TRAFFIC_INSPECTOR.md) — traffic inspector (MITM).
- [PLUGINS.md](frameworks/PLUGINS.md) — CLI plugin system overview.
- [PLUGIN_SDK.md](frameworks/PLUGIN_SDK.md) — plugin SDK reference.
- [PLUGIN_MARKETPLACE.md](frameworks/PLUGIN_MARKETPLACE.md) — plugin marketplace.
- [RADAR.md](frameworks/RADAR.md) — Radar free-model catalog overlay (optional, off by default).

## routing/

Combo routing, scoring, and replay.

- [AUTO-COMBO.md](routing/AUTO-COMBO.md) — Auto-Combo (multi-factor scoring, 19 strategies).
- [QUOTA_SHARE.md](routing/QUOTA_SHARE.md) — quota sharing engine.
- [REASONING_REPLAY.md](routing/REASONING_REPLAY.md) — reasoning replay cache.
- [REASONING_ROUTING.md](routing/REASONING_ROUTING.md) — reasoning routing rules (effort/budget rule engine).

## security/

Guardrails, compliance, stealth, and the mandatory patterns for handling public credentials and error messages.

- [GUARDRAILS.md](security/GUARDRAILS.md) — PII, prompt injection, vision guardrails.
- [COMPLIANCE.md](security/COMPLIANCE.md) — audit trails and compliance.
- [STEALTH_GUIDE.md](security/STEALTH_GUIDE.md) — TLS / fingerprint stealth.
- [PUBLIC_CREDS.md](security/PUBLIC_CREDS.md) — **mandatory** pattern for embedding public upstream OAuth client_id/secret + Firebase Web keys without tripping secret scanners.
- [ERROR_SANITIZATION.md](security/ERROR_SANITIZATION.md) — **mandatory** pattern for routing every error response through `sanitizeErrorMessage` to prevent stack-trace exposure.
- [ROUTE_GUARD_TIERS.md](security/ROUTE_GUARD_TIERS.md) — route-guard classification tiers.
- [CLI_TOKEN.md](security/CLI_TOKEN.md) — CLI machine-ID token (HMAC + legacy SHA-256) auth.
- [EGRESS_POLICY.md](security/EGRESS_POLICY.md) — egress IP family (IPv4/IPv6) policy.
- [BAN_DETECTION.md](security/BAN_DETECTION.md) — account-ban / banned-keyword detection.
- [AGENTROUTER_WAF.md](security/AGENTROUTER_WAF.md) — agentrouter.org WAF.
- [CORS.md](security/CORS.md) — CORS configuration & security.
- [MITM-TPROXY-DECRYPT.md](security/MITM-TPROXY-DECRYPT.md) — transparent MITM decrypt.
- [SUPPLY_CHAIN.md](security/SUPPLY_CHAIN.md) — supply-chain gates (SLSA, SBOM, Trivy, osv-scanner, Scorecard).
- [SOCKET_DEV_FINDINGS.md](security/SOCKET_DEV_FINDINGS.md) — supply-chain finding attestations.

## compression/

Prompt compression engines, rules, and language packs.

- [COMPRESSION_GUIDE.md](compression/COMPRESSION_GUIDE.md) — top-level compression overview.
- [COMPRESSION_ENGINES.md](compression/COMPRESSION_ENGINES.md) — available compression engines.
- [COMPRESSION_RULES_FORMAT.md](compression/COMPRESSION_RULES_FORMAT.md) — rule file format.
- [COMPRESSION_LANGUAGE_PACKS.md](compression/COMPRESSION_LANGUAGE_PACKS.md) — language packs.
- [RTK_COMPRESSION.md](compression/RTK_COMPRESSION.md) — RTK engine deep dive.
- [CONTEXT_EDITING.md](compression/CONTEXT_EDITING.md) — delegated context editing (Anthropic).
- [EXTENDING_COMPRESSION.md](compression/EXTENDING_COMPRESSION.md) — adding a custom compression engine.

## providers/

Provider-specific integration guides.

- [CLAUDE_WEB.md](providers/CLAUDE_WEB.md) — Claude Web (cookie-auth) provider.
- [CHATGPT_WEB.md](providers/CHATGPT_WEB.md) — ChatGPT Web (Plus/Pro + Codex) providers.
- [ALIBABA-QWEN-PROVIDER-FAMILIES.md](providers/ALIBABA-QWEN-PROVIDER-FAMILIES.md) — Alibaba and Qwen provider families.
- [AGENTROUTER.md](providers/AGENTROUTER.md) — AgentRouter setup.
- [ZED-DOCKER.md](providers/ZED-DOCKER.md) — Zed IDE integration under Docker.
- [CURSOR-DOCKER.md](providers/CURSOR-DOCKER.md) — Cursor model listing under Docker.

## comparison/

- [OMNIROUTE_VS_ALTERNATIVES.md](comparison/OMNIROUTE_VS_ALTERNATIVES.md) — how OmniRoute compares to alternatives.

## ops/

Release, deployment, proxies, tunnels, coverage, database, monitoring.

- [RELEASE_CHECKLIST.md](ops/RELEASE_CHECKLIST.md) — release flow checklist.
- [RELEASE_GREEN.md](ops/RELEASE_GREEN.md) — keeping the PR queue and release branch green.
- [BRANCHING_MODEL.md](ops/BRANCHING_MODEL.md) — branching & release model.
- [MERGE_TRAIN.md](ops/MERGE_TRAIN.md) — merge queue & manual merge-train runbook.
- [HOMOLOGATION.md](ops/HOMOLOGATION.md) — homologation suite (`npm run homolog`).
- [QUALITY_GATE_PLAYBOOK.md](ops/QUALITY_GATE_PLAYBOOK.md) — quality-gate playbook.
- [RUNNER_BOX.md](ops/RUNNER_BOX.md) — self-hosted runner box operations.
- [BRANCH_PROTECTION_MAIN.md](ops/BRANCH_PROTECTION_MAIN.md) — `main` branch protection.
- [CONTRIBUTION_GOLDEN_PATH.md](ops/CONTRIBUTION_GOLDEN_PATH.md) — contribution golden path (focused checks per change type).
- [COVERAGE_PLAN.md](ops/COVERAGE_PLAN.md) — test coverage plan.
- [DATABASE_GUIDE.md](ops/DATABASE_GUIDE.md) — DB schema and operations.
- [SQLITE_RUNTIME.md](ops/SQLITE_RUNTIME.md) — SQLite driver resolution chain.
- [REDIS_PRODUCTION_CONFIG.md](ops/REDIS_PRODUCTION_CONFIG.md) — Redis production configuration.
- [MONITORING_GUIDE.md](ops/MONITORING_GUIDE.md) — monitoring & observability.
- [FLY_IO_DEPLOYMENT_GUIDE.md](ops/FLY_IO_DEPLOYMENT_GUIDE.md) — Fly.io deployment.
- [VM_DEPLOYMENT_GUIDE.md](ops/VM_DEPLOYMENT_GUIDE.md) — generic VM deployment.
- [PROXY_GUIDE.md](ops/PROXY_GUIDE.md) — upstream proxy configuration.
- [TUNNELS_GUIDE.md](ops/TUNNELS_GUIDE.md) — Cloudflare tunnel and friends.

## diagrams/

Mermaid sources and exported SVG/PNG diagrams referenced from the docs above. See [diagrams/README.md](diagrams/README.md).

## i18n/

Translated mirrors of the documentation in 43 locales. See [i18n/README.md](i18n/README.md) for the supported language list.

## screenshots/

Static screenshots used by the dashboard and the README. Not part of the doc body.

---

## Auto-generated artifacts

- [reference/PROVIDER_REFERENCE.md](reference/PROVIDER_REFERENCE.md) is generated by `scripts/docs/gen-provider-reference.ts` from `src/shared/constants/providers.ts`. Do not edit by hand.
- The `/docs` UI is backed by Fumadocs MDX source generation from the subfolders above.