Buckets:
| <div align="center"> | |
| <img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="820"/> | |
| <br/> | |
| # 🚀 OmniRoute — The Free AI Gateway | |
| ### Never stop coding. Connect every AI tool to **250 providers** — **90+ free** — through one endpoint. | |
| **Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.** | |
| <br/> | |
| **RTK + Caveman compression saves 15–95% tokens. Never hit limits.** | |
| <br/> | |
| **~1.6B documented free tokens/month** — up to **~2.1B in your first month** with signup credits — aggregated across the free tiers, plus a long tail of permanently-free, no-cap providers, and the compression above stretches every one further. ([how we count →](docs/reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate)) | |
| <br/> | |
| <h3> | |
| ⭐ Star the repo if OMNIROUTE helped you save money and make your work easier. | |
| </h3> | |
| [](https://github.com/diegosouzapw/OmniRoute) | |
| <a href="https://trendshift.io/repositories/23589" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23589" alt="diegosouzapw%2FOmniRoute | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> | |
| [](https://www.star-history.com/diegosouzapw/omniroute) | |
| </br> | |
| [](#-250-ai-providers--90-free) | |
| [](#-250-ai-providers--90-free) | |
| [](docs/reference/FREE_TIERS.md) | |
| [](#%EF%B8%8F-save-1595-tokens--automatically) | |
| [](#-combos--the-flagship) | |
| [](#-quick-start) | |
| <br/> | |
| ### 💬 Join the community | |
| [](https://discord.gg/EkzRkpzKYt) | |
| [](https://t.me/omnirouteOficial) | |
| [](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) | |
| [](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI) | |
| [](https://omniroute.online) | |
| **Questions, provider tips, roadmap & support → [Discord](https://discord.gg/EkzRkpzKYt) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 Brasil](https://chat.whatsapp.com/BTGJXIyjeNIIgExvTMGGhI)** | |
| <br/> | |
| ### 🧩 Available | |
| [](https://www.npmjs.com/package/omniroute) | |
|  | |
| [](https://hub.docker.com/r/diegosouzapw/omniroute) | |
| [](LICENSE) | |
|  | |
|  | |
| [**🚀 Quick Start**](#-quick-start) • [**🎯 Combos**](#-combos--the-flagship) • [**🌐 Providers**](#-250-ai-providers--90-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ Compression**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 Website**](https://omniroute.online) | |
| [💥 The Promise](#-the-promise) • [🤔 Why](#-why-omniroute) • [🏆 What Sets Apart](#-what-sets-omniroute-apart) • [🤖 Compatible CLIs](#-compatible-clis--coding-agents) • [🖥️ Where It Runs](#%EF%B8%8F-where-omniroute-runs--anywhere) • [🔒 Private](#-private--local-first) • [🎬 In Action](#-omniroute-in-action) • [📚 Explore More](#-explore-more) • [📧 Support](#-support--community) | |
| </div> | |
| <div align="center"> | |
| <b>🌐 In 42+ languages</b> | |
| <table> | |
| <tr> | |
| <td align="center"><a href="README.md">🇺🇸</a></td> | |
| <td align="center"><a href="docs/i18n/pt-BR/README.md">🇧🇷</a></td> | |
| <td align="center"><a href="docs/i18n/pt/README.md">🇵🇹</a></td> | |
| <td align="center"><a href="docs/i18n/es/README.md">🇪🇸</a></td> | |
| <td align="center"><a href="docs/i18n/fr/README.md">🇫🇷</a></td> | |
| <td align="center"><a href="docs/i18n/it/README.md">🇮🇹</a></td> | |
| <td align="center"><a href="docs/i18n/de/README.md">🇩🇪</a></td> | |
| <td align="center"><a href="docs/i18n/nl/README.md">🇳🇱</a></td> | |
| <td align="center"><a href="docs/i18n/ru/README.md">🇷🇺</a></td> | |
| <td align="center"><a href="docs/i18n/uk-UA/README.md">🇺🇦</a></td> | |
| <td align="center"><a href="docs/i18n/pl/README.md">🇵🇱</a></td> | |
| <td align="center"><a href="docs/i18n/cs/README.md">🇨🇿</a></td> | |
| <td align="center"><a href="docs/i18n/sk/README.md">🇸🇰</a></td> | |
| <td align="center"><a href="docs/i18n/ro/README.md">🇷🇴</a></td> | |
| <td align="center"><a href="docs/i18n/hu/README.md">🇭🇺</a></td> | |
| </tr> | |
| <tr> | |
| <td align="center"><a href="docs/i18n/bg/README.md">🇧🇬</a></td> | |
| <td align="center"><a href="docs/i18n/da/README.md">🇩🇰</a></td> | |
| <td align="center"><a href="docs/i18n/fi/README.md">🇫🇮</a></td> | |
| <td align="center"><a href="docs/i18n/no/README.md">🇳🇴</a></td> | |
| <td align="center"><a href="docs/i18n/sv/README.md">🇸🇪</a></td> | |
| <td align="center"><a href="docs/i18n/zh-CN/README.md">🇨🇳</a></td> | |
| <td align="center"><a href="docs/i18n/zh-TW/README.md">🇹🇼</a></td> | |
| <td align="center"><a href="docs/i18n/ja/README.md">🇯🇵</a></td> | |
| <td align="center"><a href="docs/i18n/ko/README.md">🇰🇷</a></td> | |
| <td align="center"><a href="docs/i18n/th/README.md">🇹🇭</a></td> | |
| <td align="center"><a href="docs/i18n/vi/README.md">🇻🇳</a></td> | |
| <td align="center"><a href="docs/i18n/id/README.md">🇮🇩</a></td> | |
| <td align="center"><a href="docs/i18n/ms/README.md">🇲🇾</a></td> | |
| <td align="center"><a href="docs/i18n/phi/README.md">🇵🇭</a></td> | |
| </tr> | |
| <tr> | |
| <td align="center"><a href="docs/i18n/in/README.md">🇮🇳</a></td> | |
| <td align="center"><a href="docs/i18n/hi/README.md">🇮🇳</a></td> | |
| <td align="center"><a href="docs/i18n/gu/README.md">🇮🇳</a></td> | |
| <td align="center"><a href="docs/i18n/mr/README.md">🇮🇳</a></td> | |
| <td align="center"><a href="docs/i18n/ta/README.md">🇮🇳</a></td> | |
| <td align="center"><a href="docs/i18n/te/README.md">🇮🇳</a></td> | |
| <td align="center"><a href="docs/i18n/bn/README.md">🇧🇩</a></td> | |
| <td align="center"><a href="docs/i18n/ur/README.md">🇵🇰</a></td> | |
| <td align="center"><a href="docs/i18n/fa/README.md">🇮🇷</a></td> | |
| <td align="center"><a href="docs/i18n/ar/README.md">🇸🇦</a></td> | |
| <td align="center"><a href="docs/i18n/he/README.md">🇮🇱</a></td> | |
| <td align="center"><a href="docs/i18n/tr/README.md">🇹🇷</a></td> | |
| <td align="center"><a href="docs/i18n/az/README.md">🇦🇿</a></td> | |
| <td align="center"><a href="docs/i18n/sw/README.md">🇹🇿</a></td> | |
| </tr> | |
| </table> | |
| </div> | |
| <br/> | |
| <div align="center"> | |
| # 💰 ~1.6B Free Tokens / Month | |
| </div> | |
| > 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 **40+ provider pools / 500+ models** into one honest number and shows it live on the dashboard (`/dashboard/free-tiers`). | |
| - **~1.6B free tokens / month** (steady) — and **up to ~2.1B in your first month** with signup credits. | |
| - **Pool-deduped, honest** — we count each shared free pool **once**, so the headline isn't inflated by rate-limit ceilings the way multi-billion competitor claims are. (Counting every rate limit 24/7 would read ~10B; we don't publish that.) | |
| - **Plus the un-countable** — permanently-free, no-token-cap providers (SiliconFlow, Z.AI GLM-Flash, Kilo, OpenCode Zen…) and a **$10 OpenRouter top-up** that unlocks **+24M/mo**, both surfaced separately so they never inflate the headline. | |
| - **Per-model breakdown**, **live used / remaining** for the current month, and a transparent **terms flag** per provider. | |
|  | |
| > Preview mockup — a real screenshot lands once the `/dashboard/free-tiers` page is validated. Full methodology (pool dedupe, credit tiers, provider terms): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**. | |
| <br/> | |
| <div align="center"> | |
| # 💥 The Promise | |
| </div> | |
| > One endpoint. **250 providers.** Never stop building — and let OmniRoute pick the cheapest one that works. | |
| <table> | |
| <tr> | |
| <td width="33%" valign="top"><b>🚫 Never hit limits</b><br/><sub>Auto-fallback across 250 providers in milliseconds. Quota out? Next provider takes over — zero downtime.</sub></td> | |
| <td width="33%" valign="top"><b>💸 Save up to 95% tokens</b><br/><sub>RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions).</sub></td> | |
| <td width="33%" valign="top"><b>🆓 $0 to start</b><br/><sub>90+ providers with a free tier, 11 free <i>forever</i> (Kiro, Qoder, Pollinations, LongCat…). No card needed.</sub></td> | |
| </tr> | |
| <tr> | |
| <td width="33%" valign="top"><b>🔌 Every tool works</b><br/><sub>24+ coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config.</sub></td> | |
| <td width="33%" valign="top"><b>🧩 One endpoint</b><br/><sub>OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at <code>/v1</code> and it just works.</sub></td> | |
| <td width="33%" valign="top"><b>🛡️ Production-grade</b><br/><sub>Circuit breakers, TLS stealth, MCP (94 tools), A2A, memory, guardrails, evals. 21,000+ tests.</sub></td> | |
| </tr> | |
| </table> | |
| <br/> | |
| <br/> | |
| <div align="center"> | |
| # 🤔 Why OmniRoute? | |
| </div> | |
| > Stop juggling 10 dashboards, dead API keys, and surprise bills. | |
| | ❌ The daily pain | ✅ How OmniRoute fixes it | | |
| | ------------------------------------------------------ | ----------------------------------------------------------------------------- | | |
| | 📉 Subscription quota expires unused every month | **Maximize subscriptions** — track quota, use every token before reset | | |
| | 🛑 Rate limits stop you mid-coding | **4-tier auto-fallback** — Subscription → API → Cheap → Free, in milliseconds | | |
| | 🔥 Tool outputs (`git diff`, `grep`, logs) burn tokens | **RTK + Caveman compression** — save 15–95% eligible tokens per request | | |
| | 💸 Expensive APIs ($20–50/mo per provider) | **Cost-optimized routing** — auto-route to the cheapest viable model | | |
| | 🧰 Each AI tool wants its own setup | **One endpoint, every tool, one dashboard** | | |
| | 🌍 AI blocked in your country | **3-level proxy** + TLS fingerprint stealth — use AI from anywhere | | |
| <div align="center"> | |
| ``` | |
| ┌──────────────────────────────────────────────────────────┐ | |
| │ Your IDE / CLI (Claude Code, Cursor, Cline…) │ | |
| └─────────────────────────┬──────────────────────────────────┘ | |
| │ http://localhost:20128/v1 | |
| ▼ | |
| ┌──────────────────────────────────────────────────────────┐ | |
| │ OmniRoute — Smart Router │ | |
| │ RTK + Caveman compression · 18 routing strategies │ | |
| │ Circuit breakers · TLS stealth · MCP · A2A · Guardrails │ | |
| └─────────────────────────┬──────────────────────────────────┘ | |
| ┌─────────────┬────┴────────┬─────────────┐ | |
| ▼ Tier 1 ▼ Tier 2 ▼ Tier 3 ▼ Tier 4 | |
| SUBSCRIPTION API KEY CHEAP FREE | |
| Claude Code, DeepSeek, GLM $0.5, Kiro, Qoder, | |
| Codex, Copilot Groq, xAI MiniMax $0.2 Pollinations | |
| quota out? ───▶ budget hit? ─▶ budget hit? ─▶ always on | |
| ``` | |
| </div> | |
| <br/> | |
| <div align="center"> | |
| # 🎯 Combos — The Flagship | |
| </div> | |
| > 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 — 18 routing strategies | |
| All **18** 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 | `lkgp` | Last-Known-Good Path — sticky to the last successful target | | |
| | 16 | `auto` | 12-factor live scoring across every connection 🤖 | | |
| | 17 | `fusion` | Fan out to a panel of models + a judge synthesizes one answer 🧬 | | |
| | 18 | `pipeline` | Chain steps — each target's output feeds the next one 🔗 | | |
| <sub>The Auto-Combo engine scores every candidate on **12 factors** (health, quota, cost, latency, success rate, freshness…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).</sub> | |
| ## | |
| ### ⚖️ Quota-Share — split one subscription across a team ✨ NEW | |
| > Running several keys against the **same upstream account** (one Codex Pro plan, one Kimi key, one GLM Coding seat)? A burst on one key can burn the whole 5-hour / hourly quota and lock everyone else out. **Quota-Share** distributes a provider's time-based quota **fairly** across the keys in a pool — and it's _work-conserving_, so an idle member's slice is lent out instead of wasted. | |
| | Knob | What it controls | | |
| | ------------------------ | ------------------------------------------------------------------------------- | | |
| | ⚖️ **Allocation weight** | each key's slice of the pool — e.g. `50 / 30 / 20` | | |
| | 📐 **Dimensions** | track `%` · requests · tokens · `$`, per **5h / 7d / per-model** window | | |
| | 🚦 **Policy** | `hard` (block over share) · `soft` (deprioritize) · `burst` (use idle headroom) | | |
| | 🧱 **Cap** | absolute ceiling per key, independent of mode | | |
| ``` | |
| Pool "team-codex" · 1 Codex Pro account · 3 keys · 5-hour window | |
| ├─ alice weight 50 ██████████░░░░░░░░░░ ≤ 50% of the shared 5h quota | |
| ├─ bob weight 30 ██████░░░░░░░░░░░░░░ ≤ 30% | |
| └─ ci-bot weight 20 ████░░░░░░░░░░░░░░░░ ≤ 20% | |
| Generous mode (<50% pool used) → idle shares are lent out | |
| Strict mode (≥50% pool used) → each key held to its fair share | |
| ``` | |
| <sub>Enforced in the hot path **before** the request leaves OmniRoute, with per-(key, model) caps + session stickiness for prompt-cache integrity (now with a per-combo / global disable toggle). 📖 [Quota Sharing Engine](docs/routing/QUOTA_SHARE.md)</sub> | |
| ## | |
| ### 🧱 Resilience is built in (3 independent layers) | |
| | Layer | Scope | What it does | | |
| | -------------------------- | ----------------- | -------------------------------------------------------------------------- | | |
| | 🔌 **Circuit breaker** | whole provider | Stops hammering a provider that's failing upstream; auto-probes to recover | | |
| | 💤 **Connection cooldown** | one account / key | Skips a rate-limited key while other keys keep serving | | |
| | 🎯 **Model lockout** | provider + model | Quarantines just one quota-limited model, not the whole connection | | |
| ``` | |
| Combo: "always-on" Strategy: priority | |
| 1. cc/claude-opus-4-7 ← subscription (use it fully) | |
| 2. cx/gpt-5.5 ← second subscription | |
| 3. glm/glm-5.1 ← cheap backup ($0.5/1M) | |
| 4. kr/claude-sonnet-4.5 ← FREE, unlimited (never fails) | |
| Result: 4 layers of fallback = zero downtime | |
| ``` | |
| <sub>📖 [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)</sub> | |
| <br/> | |
| <div align="center"> | |
| # 🏆 What Sets OmniRoute Apart | |
| </div> | |
| | Feature | OmniRoute | Other routers | | |
| | -------------------------------------- | ------------------------------------------------------------------- | ------------- | | |
| | 🌐 Providers | **250** | 20–100 | | |
| | 🆓 Free providers | **90+ (11 free forever)** | 1–5 | | |
| | 🔀 Routing strategies | **18** (priority, weighted, cost-optimized, context-relay, fusion…) | 1–3 | | |
| | 🗜️ Token compression | **RTK + Caveman stacked (15–95%)** | None / 20–40% | | |
| | 🧰 Built-in MCP server | **94 tools, 3 transports, 30 scopes** | Rare | | |
| | 🤝 A2A agent protocol | **6 skills, JSON-RPC 2.0** | None | | |
| | 🧠 Memory (FTS5 + vector) | **Yes** | Rare | | |
| | 🛡️ Guardrails (PII, injection, vision) | **Yes** | Rare | | |
| | ☁️ Cloud agents | **Codex, Cursor, Devin, Jules** | None | | |
| | 🥷 TLS fingerprint stealth | **JA3/JA4 via wreq-js** | None | | |
| | 🖥️ Multi-platform | **Web · Desktop · Termux · PWA** | Web only | | |
| | 🌍 i18n | **42 locales** | 0–4 | | |
| <sub>📊 Detailed comparison vs LiteLLM, OpenRouter & Portkey → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)</sub> | |
| <br/> | |
| <div align="center"> | |
| # ✨ What's New | |
| </div> | |
| > Recent highlights from **v3.8.20 → v3.8.47**. Full history in [`CHANGELOG.md`](CHANGELOG.md). | |
| - **🗜️ Compression hardening** — a default-on **inflation guard** (discard the stacked result and send the verbatim original whenever compression would _grow_ the prompt), completed **Caveman rule packs** for German / French / Japanese (dedup + ultra) plus a new **Chinese (文言 / wényán) input pack** with zh-vs-ja auto-detection, and **RTK filters for Gradle & .NET (`dotnet`)** build output. → [Compression](docs/compression/COMPRESSION_ENGINES.md) | |
| - **💸 Honest flat-rate cost** — subscription / coding-plan providers (ChatGPT Web, grok-web, the Minimax / Kimi / GLM / Alibaba Coding plans, Xiaomi MiMo…) now read **$0** in cost analytics instead of an inflated per-token estimate, while budget / quota / routing keep estimating unchanged. → [API Reference](docs/reference/API_REFERENCE.md) | |
| - **⚖️ Quota-Share routing** — a dedicated combo strategy that spreads load across accounts by _available quota_: Deficit-Round-Robin scheduling, per-connection `max_concurrent` with cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key, model) caps, session stickiness for prompt-cache integrity (now with a per-combo / global disable toggle), and proactive saturation from upstream token-usage headers. → [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) | |
| - **🤖 One-command CLI/agent setup** — a dedicated `setup-*` command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode); `omniroute launch` / `omniroute launch-codex` are zero-config launchers. → [CLI Integrations](docs/guides/CLI-INTEGRATIONS.md) | |
| - **🛰️ Remote mode** — drive a remote OmniRoute from any machine with scoped access tokens (`omniroute connect` / `omniroute contexts` / `omniroute tokens`), plus an `omniroute login antigravity` helper that runs Google "native/desktop" OAuth on your own machine and pastes a credential blob into a remote/VPS install (where the loopback redirect is unreachable). → [Remote Mode](docs/guides/REMOTE-MODE.md) | |
| - **🧭 Smarter auto-routing** — OpenRouter-style `auto/<category>:<tier>` combos (e.g. `auto/coding:fast`, `auto/reasoning:pro`), a **Fusion** strategy (fan out to a panel of models in parallel, then synthesize via a judge), **task-aware routing** (best-fit connection per task type), per-request `X-Route-Model` override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, `web_search`-aware routing (now with **per-model web-search/web-fetch interception rules**), native **xAI Grok `/v1/responses`** routing, and **per-request Auto-Combo controls** (`X-OmniRoute-Mode` mode-preset override + `X-OmniRoute-Budget` hard USD cost ceiling, scoped to a single request). Embeddings-only and rerank-only models (JinaAI, OpenRouter custom, reranker models…) no longer disappear from the combo builder's model picker. → [Auto-Combo](docs/routing/AUTO-COMBO.md) | |
| - **🗜️ Pluggable compression** — an async pipeline of **10 composable engines** with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier **Ultra**, RTK, delegated Anthropic Context Editing, **Output Styles** (output-axis steering: terse-prose / less-code / terse-CJK), an **adaptive context-budget dial** (escalate only as far as needed to fit the context window), per-request `x-omniroute-compression` control, an opt-in offline eval harness, one-click **Headroom** proxy lifecycle management from the dashboard (Docker sidecar supported), a synthetic **compression playground** (Play lanes + A/B Compare with USD-capped fidelity verdicts), an opt-in **per-step fidelity gate** that rejects a lossy engine before it degrades the prompt, a **best-of-N candidate encoder** (GCF vs TOON — keep whichever is shorter, with an A/B bytes/token table in the studio), the vendored **GCF codec updated to spec v3.2** (nested flattening — deeply-nested payloads go from ~3% to ~32% compression vs JSON), a new **omniglyph** engine (context-as-image, ~10× fewer tokens on the converted block), **CCR ranged/grep/stats retrieval** (pull an exact byte/line slice or summary of a stored block instead of re-expanding it), a unified panel with named profiles + an active-profile selector, an opt-in **per-engine pipeline circuit-breaker**, an opt-in **LLM-tier engine** (a model pass for higher-ratio semantic compression), a **read-lifecycle engine** that collapses superseded file reads, **usage-observed prefix freeze**, a graduated **CCR retrieval-feedback ramp**, a `preserveSystemPrompt` mode enum, and a **drag-reorder pipeline editor** in the studio. → [Compression](docs/compression/COMPRESSION_ENGINES.md) | |
| - **🕵️ Transparent MITM decrypt (TPROXY)** — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → [MITM/TPROXY](docs/security/MITM-TPROXY-DECRYPT.md) | |
| - **💸 Cost telemetry everywhere** — `X-OmniRoute-*` cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HIT `X-OmniRoute-Cost-Saved` header, and per-key USD spend quotas. → [API Reference](docs/reference/API_REFERENCE.md) | |
| - **🧠 Memory you control** — opt-in int8 vector quantization (Qdrant + sqlite-vec), opt-in **typed memory decay** (aged low-value memories fade on a per-type schedule), memory off by default, and a per-request `x-omniroute-no-memory` header. → [Memory](docs/frameworks/MEMORY.md) | |
| - **🛡️ Security** — a prompt-injection guard across every LLM route (backed by a red-team suite), plus a free DuckDuckGo last-resort web search. → [Guardrails](docs/security/GUARDRAILS.md) | |
| - **🖼️ New endpoints** — `/v1/ocr` (Mistral OCR) and `/v1/audio/translations` (Whisper-style audio translation) round out the media API surface. → [API Reference](docs/reference/API_REFERENCE.md) | |
| - **🌍 Deployment & ops** — reverse-proxy `basePath` deployment (`OMNIROUTE_BASE_PATH`, e.g. serving OmniRoute under `/omniroute/`), browser-language auto-detect on first visit, per-API-key device/connection tracking (IP+UA fingerprint, masked, in-memory only), root-less MITM cert trust for user-namespaced containers (`OMNIROUTE_NO_SUDO`), server-side configured-only / available-only filters on the Free Provider Rankings page, and **Traditional Chinese (zh-TW)** localization for the frontend + CLI. → [Environment](docs/reference/ENVIRONMENT.md) | |
| - **🤝 More providers & agents** — Cursor Cloud Agent (a 4th cloud agent), CodeBuddy CN (`copilot.tencent.com`), a Google Flow video-generation provider, new gateways **DGrid** and **Pioneer AI** (Fastino Labs), inbound **xAI Grok** translators plus **Grok Build (xAI)** with an OAuth import-token flow, GPT-4 / GPT-4o-mini on the GitHub Copilot provider, multi-model **Factory Droid**, **ZenMux Free** (session-cookie free tier), **Alibaba DashScope** text-to-video (`wan2.7-t2v`), a refreshed 250-provider catalog (OrcaRouter, Wafer AI, OpenAdapter, dit.ai, TokenRouter, …), Vertex AI media generation (speech/transcription/music/video), a first-class **Ollama** local-provider card, the **SenseNova** free Token Plan (chat + text-to-image), one-click account import from CLIProxyAPI (`~/.cli-proxy-api/`), **Claude Sonnet 5** wired end-to-end, a new provider wave (**Kenari**, **SumoPod**, **X5Lab**, **Charm Hyper**, **Nube.sh**, **b.ai**, **Qiniu**, **ModelScope**, **Augment/Auggie CLI**, **ClinePass**, NVIDIA NIM image generation), Codex account import from a raw ChatGPT access token, the **Requesty** gateway (BYOK, ~200 free req/day), **Yuanbao (web)** as a cookie-session provider (DeepSeek V3/R1 + Hunyuan), the **Zed** hosted LLM aggregator (OAuth), **Claude 5 Sonnet** on the Claude Web provider, Kiro **adaptive-thinking reasoning** surfaced as `reasoning_content`, **bulk API-key add for Cloudflare Workers AI**, and **OpenVecta** (AI inference gateway). → [Providers](docs/reference/PROVIDER_REFERENCE.md) | |
| - **⚡ Local performance & infra** — a one-click local Redis launcher (`omniroute redis up`, plus a dashboard Redis panel), one-click **Cloudflare Workers** and **Deno Deploy** relay deployers wired into the proxy pool, a relay-backend selector (`OMNIROUTE_RELAY_BACKEND=ts|bifrost|auto`) so `/v1/relay` stays the stable surface while choosing the fastest backend internally, **Bifrost** (Go AI-gateway) and **Mux** (agent-orchestration daemon) promoted to first-class embedded/supervised services alongside 9Router/CLIProxyAPI, **Webshare** added as a paid fourth source in the free-proxy provider framework, and **shorthand proxy formats + protocol header mode** for bulk proxy import. → [Embedded Services](docs/frameworks/EMBEDDED-SERVICES.md) | |
| <br/> | |
| <div align="center"> | |
| # 🤖 Compatible CLIs & Coding Agents | |
| > One config — `http://localhost:20128/v1` — and **every** AI IDE or CLI runs on free & low-cost models. | |
| <div align="center"> | |
| <table> | |
| <tr> | |
| <td align="center" width="120"><a href="https://github.com/anthropics/claude-code"><img src="./public/providers/claude.svg" width="52" alt="Claude Code"/><br/><b>Claude Code</b></a></td> | |
| <td align="center" width="120"><a href="https://github.com/openai/codex"><img src="./public/providers/codex.svg" width="52" alt="Codex CLI"/><br/><b>Codex CLI</b></a></td> | |
| <td align="center" width="120"><img src="./public/providers/cursor.png" width="52" alt="Cursor"/><br/><b>Cursor</b></td> | |
| <td align="center" width="120"><img src="./public/providers/copilot.png" width="52" alt="Copilot"/><br/><b>Copilot</b></td> | |
| <td align="center" width="120"><img src="./public/providers/continue.png" width="52" alt="Continue"/><br/><b>Continue</b></td> | |
| </tr> | |
| <tr> | |
| <td align="center" width="120"><a href="https://github.com/anomalyco/opencode"><img src="./public/providers/opencode.svg" width="52" alt="OpenCode"/><br/><b>OpenCode</b></a></td> | |
| <td align="center" width="120"><a href="https://github.com/Kilo-Org/kilocode"><img src="./public/providers/kilocode.svg" width="52" alt="Kilo Code"/><br/><b>Kilo Code</b></a></td> | |
| <td align="center" width="120"><img src="./public/providers/droid.svg" width="52" alt="Droid"/><br/><b>Droid</b></td> | |
| <td align="center" width="120"><img src="./public/providers/openclaw.png" width="52" alt="OpenClaw"/><br/><b>OpenClaw</b></td> | |
| <td align="center" width="120"><img src="./public/providers/kiro.svg" width="52" alt="Kiro"/><br/><b>Kiro</b></td> | |
| <td align="center" width="120"><img src="./public/providers/command-code.svg" width="52" alt="Command Code"/><br/><b>Command</b></td> | |
| </tr> | |
| </table> | |
| </div> | |
| <div align="center"> | |
| <b>＋ also works with</b> · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · <b>any OpenAI-compatible tool</b> | |
| </div> | |
| <sub>📖 Per-tool setup for all 24+ tools → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 OpenCode plugin → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)</sub> | |
| </div> | |
| <br/> | |
| <div align="center"> | |
| # 🌐 250 AI Providers — 90+ Free | |
| </div> | |
| > The most complete catalog of any open-source router: **250 providers**, **90+ with a free tier**, **11 free forever**. | |
| <div align="center"> | |
| ### 🏢 Every major lab — through one endpoint | |
| <table> | |
| <tr> | |
| <td align="center" width="92"><picture><source media="(prefers-color-scheme:dark)" srcset="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@1.91.0/dark/openai.png"/><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/openai.svg" width="40" alt="OpenAI"/></picture><br/><sub>OpenAI</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/claude-color.svg" width="40" alt="Anthropic"/><br/><sub>Anthropic</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/gemini-color.svg" width="40" alt="Gemini"/><br/><sub>Gemini</sub></td> | |
| <td align="center" width="92"><picture><source media="(prefers-color-scheme:dark)" srcset="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@1.91.0/dark/grok.png"/><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/grok.svg" width="40" alt="xAI Grok"/></picture><br/><sub>xAI Grok</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/deepseek-color.svg" width="40" alt="DeepSeek"/><br/><sub>DeepSeek</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/mistral-color.svg" width="40" alt="Mistral"/><br/><sub>Mistral</sub></td> | |
| </tr> | |
| <tr> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/qwen-color.svg" width="40" alt="Qwen"/><br/><sub>Qwen</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/meta-color.svg" width="40" alt="Meta Llama"/><br/><sub>Meta Llama</sub></td> | |
| <td align="center" width="92"><picture><source media="(prefers-color-scheme:dark)" srcset="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@1.91.0/dark/groq.png"/><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/groq.svg" width="40" alt="Groq"/></picture><br/><sub>Groq</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/nvidia-color.svg" width="40" alt="NVIDIA"/><br/><sub>NVIDIA</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/minimax-color.svg" width="40" alt="MiniMax"/><br/><sub>MiniMax</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/cohere-color.svg" width="40" alt="Cohere"/><br/><sub>Cohere</sub></td> | |
| </tr> | |
| <tr> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/perplexity-color.svg" width="40" alt="Perplexity"/><br/><sub>Perplexity</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/huggingface-color.svg" width="40" alt="Hugging Face"/><br/><sub>HuggingFace</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/together-color.svg" width="40" alt="Together"/><br/><sub>Together</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/fireworks-color.svg" width="40" alt="Fireworks"/><br/><sub>Fireworks</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/cloudflare-color.svg" width="40" alt="Cloudflare"/><br/><sub>Cloudflare</sub></td> | |
| <td align="center" width="92"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/baidu-color.svg" width="40" alt="Baidu"/><br/><sub>Baidu</sub></td> | |
| </tr> | |
| </table> | |
| <sub>…and 220+ more — every icon resolves live from the dashboard's provider catalog. 📖 [Provider Reference](docs/reference/PROVIDER_REFERENCE.md)</sub> | |
| <br/> | |
| ### 🆓 Free Forever — $0, no card | |
| <table> | |
| <tr> | |
| <td align="center" width="150"><img src="./public/providers/agentrouter.png" width="44" alt="AgentRouter"/><br/><b>AgentRouter</b><br/><sub>GPT-5, Claude, Gemini<br/>$100 free credits</sub></td> | |
| <td align="center" width="150"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/qoder-color.svg" width="44" alt="Qoder AI"/><br/><b>Qoder AI</b><br/><sub>Kimi-K2, DeepSeek-R1<br/>Unlimited FREE</sub></td> | |
| <td align="center" width="150"><picture><source media="(prefers-color-scheme:dark)" srcset="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-png@1.91.0/dark/pollinations.png"/><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/pollinations.svg" width="44" alt="Pollinations"/></picture><br/><b>Pollinations</b><br/><sub>GPT-5, Claude, Llama 4<br/>No key needed</sub></td> | |
| <td align="center" width="150"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/longcat-color.svg" width="44" alt="LongCat"/><br/><b>LongCat</b><br/><sub>LongCat-2.0<br/>10M tokens one-time (KYC) 🔑</sub></td> | |
| </tr> | |
| <tr> | |
| <td align="center" width="150"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/cloudflare-color.svg" width="44" alt="Cloudflare AI"/><br/><b>Cloudflare AI</b><br/><sub>50+ models<br/>10K neurons/day</sub></td> | |
| <td align="center" width="150"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/nvidia-color.svg" width="44" alt="NVIDIA NIM"/><br/><b>NVIDIA NIM</b><br/><sub>129 models<br/>~40 RPM free</sub></td> | |
| <td align="center" width="150"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@1.91.0/icons/cerebras-color.svg" width="44" alt="Cerebras"/><br/><b>Cerebras</b><br/><sub>Qwen3 235B<br/>1M tokens/day</sub></td> | |
| </tr> | |
| </table> | |
| 📖 Full machine-readable catalog → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md) | |
| <br/> | |
| </div> | |
| <div align="center"> | |
| # 🖥️ Where OmniRoute Runs — Anywhere | |
| </div> | |
| > Same app, your machine, your rules. From a global npm install to **your phone** via Termux. | |
| | Platform | Install | Highlights | | |
| | ------------------------- | ---------------------------------------- | --------------------------------------------------------- | | |
| | 📦 **npm (global)** | `npm install -g 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 | | |
| | 🛠️ **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> | |
| <br/> | |
| <div align="center"> | |
| # 🔒 Private & Local-First | |
| </div> | |
| > Your keys, your machine, your data. OmniRoute is a **local proxy** — it never phones home. | |
| - 🏠 **Runs 100% on your hardware** — npm, Docker, desktop, or your phone. No OmniRoute cloud sits in the request path. | |
| - 🔐 **Credentials encrypted at rest** — API keys & OAuth tokens sealed with **AES-256-GCM**. | |
| - 🚫 **Zero telemetry by default** — your prompts go only to the providers _you_ choose, nowhere else. | |
| - 🛡️ **Hardened gateway** — API-key scoping, IP filtering, rate limits, prompt-injection guard, loopback-only process routes. | |
| - 📜 **MIT licensed & fully open-source** — audit every line, self-host forever. | |
| <sub>📖 [Authorization](docs/architecture/AUTHZ_GUIDE.md) · [Guardrails](docs/security/GUARDRAILS.md) · [Compliance](docs/security/COMPLIANCE.md)</sub> | |
| <br/> | |
| <div align="center"> | |
| # 🔌 Full CLI + A2A & MCP | |
| </div> | |
| > OmniRoute isn't just a server — it's a **full command-line cockpit** with **80+ commands**, plus open agent protocols so an AI agent can drive OmniRoute **by itself**. | |
| ### ⌨️ 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> | |
| <div align="center"> | |
| `providers` · `oauth` · `keys` · `combo` · `nodes` · `models` · `cache` · `compression` · `cost` · `usage` · `quota` · `health` · `resilience` · `telemetry` · `logs` · `audit` · `mcp` · `a2a` · `cloud` · `memory` · `skills` · `eval` · `tunnel` · `backup` · `sync` · `webhooks` · `policy` · `pricing` · `translator` · `simulate` … | |
| </div> | |
| ### 🤝 Connect an agent — and it controls OmniRoute itself | |
| Expose OmniRoute over **MCP** or **A2A** and any capable agent gets the keys to the whole gateway — routing, providers, combos, cache, compression, memory — autonomously. | |
| | Protocol | Endpoint | Use it for | | |
| | ------------------ | ----------------------------------------------- | ------------------------------------------------------ | | |
| | 🧰 **MCP (stdio)** | `omniroute --mcp` | Plug into Claude Desktop, Cursor, any MCP client | | |
| | 🌊 **MCP (HTTP)** | `http://localhost:20128/api/mcp/stream` | Remote MCP — **94 tools**, 30 scopes, full audit trail | | |
| | 📡 **MCP (SSE)** | `http://localhost:20128/api/mcp/sse` | Streaming MCP transport | | |
| | 🤝 **A2A** | `http://localhost:20128/.well-known/agent.json` | Agent-to-agent, **JSON-RPC 2.0** + SSE, 6 skills | | |
| ```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> | |
| <br/> | |
| <div align="center"> | |
| # 🗜️ Save 15–95% Tokens — Automatically | |
| </div> | |
| > **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 10 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) (⭐ 78K+), [LLMLingua-2](https://github.com/microsoft/LLMLingua), and [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR). | |
| ### 🧱 The 10-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 | **RTK** | Smart tool-result filtering, dedup & truncation (command-aware) | | |
| | 4 | **Headroom** | Lossless tabular compaction of homogeneous JSON arrays, flat or nested (~30%), via a vendored **GCF** codec (spec v3.2) | | |
| | 5 | **Relevance** | Extractive sentence scoring against the last user query | | |
| | 6 | **Caveman** | Rule-based prose compression (~65–75% on output) | | |
| | 7 | **LLMLingua-2** | ML semantic pruning via MobileBERT ONNX — code-safe, async | | |
| | 8 | **Lite** | Whitespace + image-URL trimming (latency-light baseline) | | |
| | 9 | **Aggressive** | Summarization + progressive aging of old turns | | |
| | 10 | **Ultra** | Heuristic token pruning with an optional small-model (SLM) tier | | |
| 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.** ✅ | |
| <br/> | |
| ### 📖 How it works — pipeline, architecture & savings math | |
| ``` | |
| Client (10,000 tok) ──▶ OmniRoute Compression (10 engines) ──▶ Provider (~1,080 tok, up to 95% saved) | |
| ``` | |
| 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. | |
| ### 🎚️ Beyond the engines — output styles, the adaptive dial & per-request control | |
| The 10 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=<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) | |
| <br/> | |
| <div align="center"> | |
| # ⚡ Quick Start | |
| </div> | |
| **1) Install & run** | |
| ```bash | |
| npm install -g omniroute | |
| omniroute | |
| ``` | |
| 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. | |
| <br/> | |
| ## 📦 More install methods — Docker, source, pnpm, Arch | |
| **🐳 Docker** | |
| ```bash | |
| docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ | |
| -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest | |
| ``` | |
| **🛠️ From source** | |
| ```bash | |
| cp .env.example .env && npm install | |
| PORT=20128 npm run dev | |
| ``` | |
| **📦 pnpm** | |
| ```bash | |
| pnpm add -g 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. Build the image | |
| podman build --target runner-base -t omniroute:base . | |
| # 2. Fix data directory permissions for rootless Podman | |
| mkdir -p data && podman unshare chown 1000:1000 ./data | |
| # 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet) | |
| echo "CONTAINER_HOST=podman" >> .env | |
| podman compose --profile base up -d | |
| ``` | |
| 📖 [Podman Guide](contrib/podman/README.md) — Quadlet setup, podman-compose, Quadlet. | |
| **⚡ 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 -g 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. | |
| <br/> | |
| <div align="center"> | |
| # 🎬 OmniRoute in Action | |
| </div> | |
| <div align="center"> | |
| <table> | |
| <tr> | |
| <td align="center" width="280"> | |
| <a href="https://www.youtube.com/watch?v=Rxdc36yUyOQ"><img src="https://img.youtube.com/vi/Rxdc36yUyOQ/maxresdefault.jpg" alt="Guia em Português" width="260"/></a><br/> | |
| <b>🇧🇷 Português</b><br/><sub>Guia completo</sub> | |
| </td> | |
| <td align="center" width="280"> | |
| <a href="https://www.youtube.com/watch?v=CMzyOiUyEVc"><img src="https://img.youtube.com/vi/CMzyOiUyEVc/maxresdefault.jpg" alt="English Guide" width="260"/></a><br/> | |
| <b>🇺🇸 English</b><br/><sub>Complete walkthrough</sub> | |
| </td> | |
| <td align="center" width="280"> | |
| <a href="https://www.youtube.com/watch?v=il_5Ii6v4-Y"><img src="https://img.youtube.com/vi/il_5Ii6v4-Y/maxresdefault.jpg" alt="Руководство" width="260"/></a><br/> | |
| <b>🇷🇺 Русский</b><br/><sub>Полное руководство</sub> | |
| </td> | |
| </tr> | |
| </table> | |
| </div> | |
| <div align="center"> | |
| > 🎬 **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. | |
| <br/> | |
| </div> | |
| <div align="center"> | |
| # 📚 Explore More | |
| </div> | |
| <details> | |
| <summary><b>💰 Pricing at a glance & the $0 Free Stack (11 providers)</b></summary> | |
| <br/> | |
| | Tier | Example | Cost | | |
| | --------------------------- | ---------------------------------------- | ---------- | | |
| | 💳 **Subscription** | Claude Code Pro / Codex / Copilot | $10–200/mo | | |
| | 🔑 **API Key (free tiers)** | NVIDIA NIM, Cerebras, Groq | **FREE** | | |
| | 💰 **Cheap** | GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M | pennies | | |
| | 🆓 **Free Forever** | Kiro, Qoder, Qwen, Pollinations, LongCat | **$0** | | |
| **The $0 Free Stack — combine into one unbreakable combo:** | |
| | Provider | Prefix | Free models | Quota | | |
| | ----------------- | ----------- | ----------------------------------------------- | ------------------ | | |
| | **Kiro** | `kr/` | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | 50 credits/mo | | |
| | **Qoder** | `if/` | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 | ♾️ Unlimited | | |
| | **Qwen** | `qw/` | qwen3-coder-plus/flash/next | ♾️ Unlimited | | |
| | **Pollinations** | `pol/` | GPT-5, Claude, Gemini, DeepSeek, Llama 4 | No key needed | | |
| | **LongCat** | `lc/` | LongCat-2.0 | 10M one-time (KYC) | | |
| | **Cloudflare AI** | `cf/` | 50+ models | 10K neurons/day | | |
| | **NVIDIA NIM** | `nvidia/` | 129 models | ~40 RPM | | |
| | **Cerebras** | `cerebras/` | Qwen3 235B, GPT-OSS 120B | 1M tok/day | | |
| > 💡 The dashboard "cost" is a **savings tracker**, not a bill — OmniRoute never charges you. A "$290 total cost" using free models means **$290 saved**. | |
| 📖 Complete free directory → [`docs/reference/FREE_TIERS.md`](docs/reference/FREE_TIERS.md) — 25+ providers, quotas, base URLs. | |
| </details> | |
| <details> | |
| <summary><b>🎯 Use Cases — ready-made combo playbooks</b></summary> | |
| <br/> | |
| **$0 forever:** | |
| ``` | |
| 1. kr/claude-sonnet-4.5 (Kiro — ~50 credits/mo per acct) | |
| 2. if/kimi-k2-thinking (Qoder — unlimited) | |
| 3. pol/gpt-5 (Pollinations — no key) | |
| 4. lc/LongCat-2.0 (10M one-time backup, KYC) | |
| Compression: aggressive (~50%) → double your free quota · Cost: $0/mo | |
| ``` | |
| **24/7 no interruptions:** chain 2 subscriptions → cheap → free for 5 layers of fallback. | |
| **Blocked region:** free providers + global/per-provider proxy → access AI from any country. | |
| **Max savings:** subscription + cheap backup + `ultra` compression (~75%) → ~$150–300/mo saved for heavy users. | |
| </details> | |
| <details> | |
| <summary><b>🌍 Bypass geo-blocks — 3-level proxy + stealth</b></summary> | |
| <br/> | |
| 🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 In a blocked region? OmniRoute's **3-level proxy** (Global / Per-Provider / Per-Connection) proxies API requests, OAuth flows, connection tests, token refresh & model sync. | |
| - **Protocols:** HTTP/HTTPS, SOCKS5, authenticated proxies | |
| - **🆓 1proxy marketplace** — hundreds of free validated proxies, quality scores, auto-rotation | |
| - **Anti-detection** — TLS fingerprint spoofing (`wreq-js`), CLI fingerprint matching, proxy IP preservation | |
| 📖 [`docs/ops/PROXY_GUIDE.md`](docs/ops/PROXY_GUIDE.md) | |
| </details> | |
| <details> | |
| <summary><b>✨ Full feature list — 30+ capabilities (memory, evals, observability)</b></summary> | |
| <br/> | |
| **Routing:** 18 strategies · task-aware smart routing · thinking budget controls · wildcard routing · system prompt injection. | |
| **Compatibility:** OpenAI ↔ Claude ↔ Gemini ↔ Responses API · auto OAuth refresh (PKCE, 8 providers) · multi-account round-robin · Batch + Files API · live OpenAPI 3.0. | |
| **Protocols:** MCP (94 tools, 3 transports, 30 scopes) · A2A (JSON-RPC 2.0, SSE, 6 skills) · ACP · cloud agents (Codex, Cursor, Devin, Jules). | |
| **Plugins:** custom plugin marketplace (system-configured registry URL with SSRF-guarded fetch) · install / enable / disable · Notion + Obsidian knowledge-base integrations (WebDAV file server, vault search, note CRUD). | |
| **Embedded services:** one-click install & lifecycle management of local sidecar services (CLIProxy, NineRouter). | |
| **Quality & Ops:** built-in **Evals** (golden-set: exact/contains/regex/custom) · guardrails (PII, injection, vision) · health dashboard · p50/p95/p99 telemetry · webhooks · compliance audit. | |
| **AI Agent Skills:** drop-in markdown manifests — point any agent at a `skills/*/SKILL.md` manifest. 43 skills available. | |
| 📖 [MCP Server](open-sse/mcp-server/README.md) · [A2A Server](src/lib/a2a/README.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md) · [Features Gallery](docs/guides/FEATURES.md) | |
| </details> | |
| <details> | |
| <summary><b>📖 Setup, env vars & FAQ</b></summary> | |
| <br/> | |
| | Env var | Default | Purpose | | |
| | ----------------- | -------------- | -------------------------------- | | |
| | `PORT` | `20128` | API + dashboard port | | |
| | `REQUIRE_API_KEY` | `false` | Require API key for all requests | | |
| | `DATA_DIR` | `~/.omniroute` | Database & config storage | | |
| **Will I be charged by OmniRoute?** No — it's free, open-source software on your machine. You only pay paid providers directly. OmniRoute has no billing system. | |
| **Are FREE providers really unlimited?** Mostly — Qoder, Pollinations, LongCat, and Cloudflare are free with no per-account credit cap. Kiro is free too but capped at ~50 credits/month per account. Stack multiple free providers in a combo and auto-fallback keeps you serving for $0. | |
| **Will compression hurt quality?** No — it only compresses the **input**; code, URLs, JSON are always protected. | |
| **Does it work where AI is blocked?** Yes — 3-level proxy + 1proxy marketplace reach all 250 providers. | |
| 📖 [User Guide](docs/guides/USER_GUIDE.md) · [API Reference](docs/reference/API_REFERENCE.md) · [Environment Config](docs/reference/ENVIRONMENT.md) | |
| </details> | |
| <details> | |
| <summary><b>🐛 Troubleshooting</b></summary> | |
| <br/> | |
| | Problem | Quick fix | | |
| | ----------------------------------------- | ------------------------------------------------------------- | | |
| | "Language model did not provide messages" | Provider quota exhausted → use a combo fallback | | |
| | Rate limiting (429) | Add fallback: `cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` | | |
| | OAuth token expired | Auto-refreshed; if stuck, delete + re-auth in Providers | | |
| | `unsupported_country_region_territory` | Configure proxy in Settings → Proxy | | |
| | Docker SQLite locks | Use `--stop-timeout 40` for clean WAL checkpoint | | |
| | Node runtime errors | Use Node `>=22.0.0 <23` or `>=24.0.0 <27` | | |
| 🐛 **Reporting a bug?** Run `npm run system-info` and attach `system-info.txt`. 📖 [`docs/guides/TROUBLESHOOTING.md`](docs/guides/TROUBLESHOOTING.md) | |
| </details> | |
| <details> | |
| <summary><b>📸 Dashboard screenshots</b></summary> | |
| <br/> | |
| | Page | Screenshot | Page | Screenshot | | |
| | ---------- | ------------------------------------------------- | ---------- | --------------------------------------------- | | |
| | Providers |  | Combos |  | | |
| | Analytics |  | Health |  | | |
| | Translator |  | Settings |  | | |
| | CLI Tools |  | Usage Logs |  | | |
| </details> | |
| <br/> | |
| <div align="center"> | |
| # 📧 Support & Community | |
| > 💬 **Chat with the community** — Discord, Telegram & WhatsApp (🌍 / 🇧🇷) links are at the [top of this README](#-join-the-community). | |
| - 🌍 **Website**: [omniroute.online](https://omniroute.online) | |
| - 🐙 **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) | |
| - 🐛 **Issues**: [report a bug](https://github.com/diegosouzapw/OmniRoute/issues) (attach `npm run system-info` output) | |
| - 🤝 **Contributing**: see [CONTRIBUTING.md](CONTRIBUTING.md) or pick a `good first issue` | |
| </div> | |
| --- | |
| <br/> | |
| <div align="center"> | |
| ## 🛠️ Tech Stack | |
| </div> | |
| - **Runtime**: Node.js 22.x or 24.x LTS (24 LTS recommended) — `>=22.0.0 <23 || >=24.0.0 <27` | |
| - **Language**: TypeScript 6.0 — **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0) | |
| - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4 | |
| - **Database**: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills | |
| - **Schemas**: Zod (MCP tool I/O validation, API contracts) | |
| - **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) | |
| - **Streaming**: Server-Sent Events (SSE) + WebSocket bridge (`/v1/ws`) | |
| - **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization | |
| - **Testing**: Node.js test runner + Vitest (**21,000+ test cases** across 2,586 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) | |
| - **Website**: [omniroute.online](https://omniroute.online) | |
| - **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) | |
| - **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) | |
| - **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing | |
| <div align="center"> | |
| <br/> | |
| ## 📖 Documentation | |
| </div> | |
| ### 📘 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) | 12-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) | 25+ free API providers consolidated directory | | |
| | [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) | 95 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 | | |
| | [Changelog](CHANGELOG.md) | Full per-version release history | | |
| | [Security Policy](SECURITY.md) | Vulnerability reporting and security practices | | |
| | [i18n Guide](docs/guides/I18N.md) | 40+ 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 21,000+ test suite | | |
| <br/> | |
| <div align="center"> | |
| # ⭐ Top Contributors | |
| > OmniRoute is shaped by a passionate open-source community. These individuals have made exceptional contributions that directly impact the quality, stability, and reach of the project. **Thank you.** | |
| <table> | |
| <tr> | |
| <td align="center" width="160"> | |
| <a href="https://github.com/oyi77"> | |
| <img src="https://github.com/oyi77.png" width="40" style="border-radius:50%" alt="oyi77"/><br/> | |
| <b>oyi77</b> | |
| </a><br/> | |
| <sub>🥇 189 commits • +155K lines</sub><br/> | |
| <sub>Analytics engine, SQL aggregations,<br/>proxy marketplace, test coverage</sub> | |
| </td> | |
| <td align="center" width="160"> | |
| <a href="https://github.com/christopher-s"> | |
| <img src="https://github.com/christopher-s.png" width="40" style="border-radius:50%" alt="Chris Staley"/><br/> | |
| <b>Chris Staley</b> | |
| </a><br/> | |
| <sub>🥈 70 commits • +5.7K lines</sub><br/> | |
| <sub>SSE stream hardening, Responses API,<br/>Gemini pagination, test regression fixes</sub> | |
| </td> | |
| <td align="center" width="160"> | |
| <a href="https://github.com/zenobit"> | |
| <img src="https://github.com/zenobit.png" width="40" style="border-radius:50%" alt="zenobit"/><br/> | |
| <b>zenobit</b> | |
| </a><br/> | |
| <sub>🥉 62 commits • +24K lines</sub><br/> | |
| <sub>CI/CD pipeline, i18n for 33 languages,<br/>Void Linux package, platform fixes</sub> | |
| </td> | |
| <td align="center" width="160"> | |
| <a href="https://github.com/rdself"> | |
| <img src="https://github.com/rdself.png" width="40" style="border-radius:50%" alt="R.D. & Randi"/><br/> | |
| <b>R.D. & Randi</b> | |
| </a><br/> | |
| <sub>🏅 108 commits • +30K lines</sub><br/> | |
| <sub>Endpoints page, tunnel integrations,<br/>Docker workflows, A2A status, compression UI</sub> | |
| </td> | |
| <td align="center" width="160"> | |
| <a href="https://github.com/benzntech"> | |
| <img src="https://github.com/benzntech.png" width="40" style="border-radius:50%" alt="benzntech"/><br/> | |
| <b>benzntech</b> | |
| </a><br/> | |
| <sub>🏅 22 commits • +7.5K lines</sub><br/> | |
| <sub>Electron desktop app, auto-updater,<br/>release build workflows, cross-platform CI</sub> | |
| </td> | |
| <td align="center" width="160"> | |
| <a href="https://github.com/herjarsa"> | |
| <img src="https://github.com/herjarsa.png" width="40" style="border-radius:50%" alt="herjarsa"/><br/> | |
| <b>herjarsa</b> | |
| </a><br/> | |
| <sub>🏅 21 commits • +6K lines</sub><br/> | |
| <sub>Zero-latency combos, vision-bridge auto-routing,<br/>catalog context-length, resilience 429 hints</sub> | |
| </td> | |
| </tr> | |
| </table> | |
| > 🙏 These contributors' features, bug fixes, and infrastructure improvements are a **core part** of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them. | |
| </div> | |
| --- | |
| <br/> | |
| <div align="center"> | |
| ## 👥 280+ Contributors | |
| </div> | |
| [](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) | |
| ### How to Contribute | |
| 1. Fork the repository | |
| 2. Create your feature branch (`git checkout -b feature/amazing-feature`) | |
| 3. Commit your changes (`git commit -m 'Add amazing feature'`) | |
| 4. Push to the branch (`git push origin feature/amazing-feature`) | |
| 5. Open a Pull Request | |
| 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 | |
| ``` | |
| <br/> | |
| <div align="center"> | |
| ## 📊 Stars | |
| <a href="https://www.star-history.com/?repos=diegosouzapw%2FOmniRoute&type=date&legend=top-left"> | |
| <picture> | |
| <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/OmniRoute&type=date&theme=dark&legend=top-left&sealed_token=XP_ycEjv7s31p1edvhsMOXry51OWYsUjDRWjflSG7jQKRpO9hPGg7i_EHvwhI6QtrARTMH-YGjJhi8sumRYflEJD0DPlH_MMHjizhBYCX8fbHFrHEiNvVA" /> | |
| <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/OmniRoute&type=date&legend=top-left&sealed_token=XP_ycEjv7s31p1edvhsMOXry51OWYsUjDRWjflSG7jQKRpO9hPGg7i_EHvwhI6QtrARTMH-YGjJhi8sumRYflEJD0DPlH_MMHjizhBYCX8fbHFrHEiNvVA" /> | |
| <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/OmniRoute&type=date&legend=top-left&sealed_token=XP_ycEjv7s31p1edvhsMOXry51OWYsUjDRWjflSG7jQKRpO9hPGg7i_EHvwhI6QtrARTMH-YGjJhi8sumRYflEJD0DPlH_MMHjizhBYCX8fbHFrHEiNvVA" /> | |
| </picture> | |
| </a> | |
| <br/> | |
| <div align="center"> | |
| ## 🌍 StarMapper | |
| <a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute"> | |
| <picture> | |
| <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" /> | |
| <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" /> | |
| <img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" /> | |
| </picture> | |
| </a> | |
| </div> | |
| <br/> | |
| <div align="center"> | |
| ## 🙏 Acknowledgments | |
| </div> | |
| 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 June 2026 — go give these projects a star. | |
| ### 🧬 Lineage & gateway | |
| | Project | ⭐ | How it inspired OmniRoute | | |
| | ------------------------------------------------------------------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------- | | |
| | **[9router](https://github.com/decolua/9router)** · decolua | 19.0k | 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)** · router-for-me | 38.8k | The Go implementation that inspired this JavaScript / TypeScript port. | | |
| | **[LiteLLM](https://github.com/BerriAI/litellm)** · BerriAI | 52.1k | 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)** · JuliusBrussee | 78.2k | 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)** · rtk-ai | 67.3k | 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)** · headroomlabs-ai | 54.5k | Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern. | | |
| | **[LLMLingua](https://github.com/microsoft/LLMLingua)** · Microsoft | 6.4k | 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)** · atjsh | 28 | The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine. | | |
| | **[Troglodita](https://github.com/leninejunior/troglodita)** · Lenine Júnior | 16 | 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)** · DietrichGebert | 68.8k | 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)** · toon-format | 24.7k | 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)** · Blackwell Systems | 14 | 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)** · ooples | 421 | Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine. | | |
| | **[token-savior](https://github.com/Mibayy/token-savior)** · Mibayy | 1.0k | Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction. | | |
| | **[token-saver](https://github.com/ppgranger/token-saver)** · ppgranger | 110 | 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)** · alexgreensh | 1.5k | "Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking. | | |
| | **[TokenMizer](https://github.com/Shweta-Mishra-ai/tokenmizer)** · Shweta-Mishra-ai | 2 | A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design. | | |
| | **[OmniCompress](https://github.com/jessefreitas/OmniCompress)** · jessefreitas | 2 | 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)** · Atlassian Labs | 89 | MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction. | | |
| | **[RepoMapper](https://github.com/pdavis68/RepoMapper)** · pdavis68 | 181 | Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration. | | |
| | **[quiet-shell-mcp](https://github.com/mrsimpson/quiet-shell-mcp)** · mrsimpson | 4 | Declarative shell-output reduction over MCP — validated our declarative bash-output compaction. | | |
| | **[ts-morph](https://github.com/dsherret/ts-morph)** · David Sherret | 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)** · mem0ai | 59.8k | Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture. | | |
| | **[Letta (MemGPT)](https://github.com/letta-ai/letta)** · letta-ai | 23.6k | Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model. | | |
| | **[WFGY](https://github.com/onestardao/WFGY)** · onestardao | 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)** · chouzz | 48 | 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)** · InterceptSuite | 5.3k | 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)** · SST / OpenCode | 5.6k | Open database of AI model specs, pricing and capabilities — synced natively into our model catalog. | | |
| | **[React Flow / xyflow](https://github.com/xyflow/xyflow)** · xyflow | 37.4k | The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio. | | |
| | **[LangGraph](https://github.com/langchain-ai/langgraph)** · LangChain | 36.1k | LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view. | | |
| | **[Langfuse](https://github.com/langfuse/langfuse)** · Langfuse | 30.1k | Its trace → span → generation observability model shaped our Compression Studio waterfall. | | |
| | **[Kiali](https://github.com/kiali/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)** · LobeHub | 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)** · tldrsec | 708 | 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 composes with OmniRoute | | |
| | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | **[CodeWebChat](https://github.com/robertpiosik/CodeWebChat)** · robertpiosik | Editor-side companion — VS Code + browser extension that autofills 15+ chatbot web UIs with editor context. Owns the free-web-UI rail alongside OmniRoute's API rail; can point its API mode at OmniRoute. | | |
| ## ❤️ Support | |
| OmniRoute is free and open source, built and maintained in the open. If it saves you time or money, consider supporting development: | |
| - ⭐ **Star the repo** — it genuinely helps visibility | |
| - 💖 **[GitHub Sponsors](https://github.com/sponsors/diegosouzapw)** — fund ongoing maintenance and new providers | |
| - 🐛 **Report bugs and share feedback** in [Discussions](https://github.com/diegosouzapw/OmniRoute/discussions) | |
| ## 📄 License | |
| MIT License - see [LICENSE](LICENSE) for details. | |
| --- | |
| <div align="center"> | |
| **[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community. | |
| <sub>OmniRoute v3.8.43 · Node ≥22.0.0 · MIT License · <a href="https://omniroute.online">omniroute.online</a></sub> | |
| </div> | |
| <!-- GitHub Discussions enabled for community Q&A --> | |
Xet Storage Details
- Size:
- 94.4 kB
- Xet hash:
- e3d6bdbf34176d9adb883891f525df33675f853eba80a58c6eb3fedf65af73fe
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.