# 🚀 OmniRoute — The Free AI Gateway

OmniRoute — Never stop coding. Every AI tool → 345 providers — 90+ free — through one endpoint. Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini with automatic fallback while a healthy target is available. RTK + Caveman stacked compression saves 15–95% tokens on eligible workloads (~89% in the documented stacked example). 345 AI providers · 90+ free tiers · ~1.51B free tokens/mo · 19 routing strategies · $0 to start.

## 💰 ~1.51B Free Tokens / Month

> Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute aggregates **38 documented recurring pools / 446 cataloged free-tier entries** 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)**. > > _{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.}

⭐ Star the repo if OMNIROUTE helped you save money and make your work easier.

[![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)

[![Star History Rank](https://api.star-history.com/badge?repo=diegosouzapw/OmniRoute&theme=dark)](https://www.star-history.com/diegosouzapw/omniroute) [![olud.ai](https://olud.ai/badge.php?tool=diegosouzapw-omniroute)](https://olud.ai/project/diegosouzapw-omniroute.html) ### 💬 Join the community **👋 Follow the maintainer — get new providers, releases & tips first:** [![Follow Diego on LinkedIn](https://img.shields.io/badge/Follow_Diego_on-LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/diegosouzapw/) [![Follow @diegosouzapw on GitHub](https://img.shields.io/github/followers/diegosouzapw?style=for-the-badge&logo=github&logoColor=white&label=Follow%20on%20GitHub&color=181717)](https://github.com/diegosouzapw) [![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/U47eFqAXCn) [![Telegram](https://img.shields.io/badge/Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/omnirouteOficial) [![WhatsApp Global](https://img.shields.io/badge/WhatsApp_Global-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) [![WhatsApp Brasil](https://img.shields.io/badge/WhatsApp_Brasil-25D366?style=for-the-badge&logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/LTSpdFhXTxjH4R6CCNiKWz) [![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) **Questions, provider tips, roadmap & support → [Discord](https://discord.gg/U47eFqAXCn) · [Telegram](https://t.me/omnirouteOficial) · WhatsApp [🌍 Global](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) / [🇧🇷 Brasil](https://chat.whatsapp.com/LTSpdFhXTxjH4R6CCNiKWz)**
## 📈 The Gateway Keeps Growing

| | v3.8.49 | **v3.8.50** | `v3.8.51+` | | ------------------------- | :-----: | :-----------------------: | :---------: | | 🌐 Providers | 290 | **345** | more queued | | 🧠 Unique chat model IDs | 1185 | **1273** | — | | 🖼️ Modality Bridge | — | 🆕 vision + audio + video | — | | 📡 Radar free catalog | — | 🆕 opt-in | — | | ⚖️ Quota-aware scheduling | — | 🆕 Quota-Share | — | | 📊 Quota telemetry | — | 🆕 live | — | **→ [Roadmap](ROADMAP.md) — riding the rail to `v3.9.0 LTS`**

## 🧩 Available [![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute) ![NPM Monthly](https://img.shields.io/npm/dm/omniroute?label=npm/month&color=cb3837&logo=npm) [![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE) ![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?label=docker%20pulls&logo=docker&color=2496ED) ![Electron Downloads](https://img.shields.io/github/downloads/diegosouzapw/omniroute/total?style=flat&label=electron%20downloads&logo=electron&color=47848F)

🚀 Start	🚀 Quick Start	📦 Install	🆓 Zero-config
💡 Learn	💥 The Promise	🤔 Why OmniRoute	🏆 What Sets Apart
⚙️ Features	🎯 Combos	🌐 Providers	🔌 CLI & MCP
	🗜️ Compression	🖥️ Where It Runs	🔒 Private
👀 See it	🎬 In Action	✨ What's New	🤖 Compatible CLIs
💚 Support	💚 Support / Donate	💬 Community	💖 Sponsors
📦 Project	🛠️ Tech Stack	📖 Docs	👥 Contributors

🌐 In 43 languages

## 🆓 Works the second you install it — no keys, no config

```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!"}]}' ``` _{Prefer a specific free backend? Call `oc/…` (OpenCode Free) directly. Then graduate to `auto` and let OmniRoute pick.} _{📦 Copy-paste quickstart scripts for **Python, Node.js, PHP, and cURL** → [`examples/quickstart/`](examples/quickstart/)}

# 💥 The Promise

# 🤔 Why OmniRoute?

OmniRoute request flow: your IDE or CLI (Claude Code, Cursor, Cline…) calls one local endpoint (http://localhost:20128/v1); the OmniRoute Smart Router (RTK + Caveman compression, 19 routing strategies, circuit breakers, TLS stealth, MCP, A2A, guardrails) can fall back across 4 provider tiers while an eligible healthy target remains — Tier 1 Subscription, Tier 2 API Key, Tier 3 Cheap and Tier 4 Free.

## 🤝 Supported by our Open Source Friends

> **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 (kimi-k3) and the Kimi Code coding plan (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 →

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/<model>). Get an API key →

_{Links tagged aff=omniroute are partner links. They fund the project at no extra cost to you.}

_{🎟️ Affiliates Promo — free signup coupons from providers we don't sponsor (click to expand)}

_{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.}

_AgentRouter
_{agentrouter.org} _{AgentRouter — 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 →}

_{⚠️ Affiliate link — OmniRoute has no sponsorship or partnership with this provider.}

_{Know another provider with a generous free signup coupon that benefits OmniRoute users? Open an issue and we'll add it here.}

## 🎯 Combos — The Flagship

All 19 combo routing strategies animated — one tile per strategy: priority, fill-first, weighted, round-robin, p2c, least-used, random, strict-random, cost-optimized, headroom, reset-window, reset-aware, context-relay, context-optimized, cache-optimized, lkgp, auto, fusion, pipeline. See the table above for what each one does.

> A **combo** is a chain of models OmniRoute routes across **automatically**. If quota runs out, a provider fails, or costs spike, the combo can move to the next eligible healthy model. 🛡️ ### ⚡ 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`	15-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 🔗

_{The Auto-Combo engine scores every candidate on **15 factors** (health, quota, cost, latency, task fit, quality, session availability…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).} ## ### 🧱 Resilience is built in (3 independent layers)

OmniRoute resilience — 3 independent self-healing layers, the right layer for the right failure. Layer 1 provider circuit breaker (whole provider): trips only on 408/5xx, thresholds OAuth 10× / API-key 15× / local 2×, resets 60s/30s/15s into a HALF-OPEN probe, lazy recovery; while OPEN the combo reroutes to the next provider. Layer 2 connection cooldown (one key/account): base 5s OAuth / 3s API-key, exponential ×2 backoff with anti-thundering-herd guard, 429 honors Retry-After, success clears all error state; one cooling key is skipped while sibling keys keep serving. Layer 3 model lockout (one model): per-model 429, local 404 or mode denials lock just that model — never the whole connection. Terminal states (banned, expired, credits exhausted) are for the operator, not cooldowns.

_{📖 [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)}

## 🏆 What Sets OmniRoute Apart

_{📊 Full methodology & per-feature detail vs 9router, OpenRouter, CLIProxyAPI & LiteLLM → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md)}
## 💚 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
🐙 GitHub Sponsors	One-off or monthly · zero platform fee	github.com/sponsors/diegosouzapw
☕ Ko-fi	Quick one-off tip, no signup for the donor	ko-fi.com/diegosouzapw
🧋 Buy Me a Coffee	Small, informal gesture	buymeacoffee.com/diegosouzapw
🖐 Liberapay	Recurring · non-profit · open source	liberapay.com/diegosouzapw
🇧🇷 PIX (Brazil)	Instant, no fees	key & QR below
₿ Crypto	BTC · ETH · USDT-TRC20 · USDC-Solana	addresses below

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

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`

_{⚠️ Send each coin only on the network shown — sending on the wrong network can lose the funds.}

🐛 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 for guidance on managing local environment files and secrets.

## 📡 OmniRoute Radar The main free-tier headline remains **~1.51B tokens/month** from the documented, pool-deduplicated catalog above. Temporary provider signup credits can separately lift the first month to **~2.13B**. 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)**.

## ✨ What's New

> 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** — 12 registered `setup-*` commands; `omniroute run` launches 7 CLIs (Claude Code, Codex, Aider, Goose, OpenCode, Qwen Code, Gemini CLI); `omniroute configure` supports 9 targets with an interactive provider+model picker and 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/:` 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, Segmind and ElevenLabs. → [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 **345-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) - **🔎 First-class search** — X Search and Firecrawl through `POST /v1/search` and MCP, with a credential-free DuckDuckGo fallback when no search provider is configured. → [API Reference](docs/reference/API_REFERENCE.md) - **🧩 Safer plugin runtime** — checksum-verified marketplace installs, request-header context and streaming-completion lifecycle hooks. → [Plugin Guide](docs/frameworks/PLUGINS.md) - **🖥️ Desktop & deployment** — Electron remote-server attach through `OMNIROUTE_REMOTE_URL`, plus systemd installation and autostart flows. → [Electron Guide](docs/guides/ELECTRON_GUIDE.md) - **🎞️ Full modality routing** — vision and audio-to-text bridges, video passthrough, and combo/fallback routing for image generation. → [API Reference](docs/reference/API_REFERENCE.md) - **🎛️ Exact model control** — provider-scoped durable aliases and enforced per-model context, input and output limits. → [API Reference](docs/reference/API_REFERENCE.md) - **🆓 Faster free onboarding** — reviewable one-click connection of eligible no-auth providers. → [Provider Reference](docs/reference/PROVIDER_REFERENCE.md) - **🧠 Auditable routing** — optional encrypted reasoning replay, plus the Telegram Mini App chat bridge. → [Reasoning Replay](docs/routing/REASONING_REPLAY.md)

## 🤖 Compatible CLIs & Coding Agents > One config — `http://localhost:20128/v1` — and **every** AI IDE or CLI runs on free & low-cost models.

_{Claude Code}	_{Codex CLI}	_Cline	_{Kilo Code}	_{Zoo Code}	_Continue
_Aider	_ForgeCode	_jcode	_{DeepSeek TUI}	_CodeWhale	_OpenCode
_{Factory Droid}	_{Copilot CLI}	_{Cursor CLI}	_Smelt	_Pi	_{Grok Build}
_{Hermes Agent}	_OpenClaw	_Goose	_{Open Interpreter}	_{Warp AI}	_{Agent Deck}

＋ also works with · Kiro · Command Code · Antigravity · Windsurf · AMP · any OpenAI-compatible tool

_{📖 Per-tool setup for all 35 tools (26 CLI Code's + 9 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)}

**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 `), `--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)

## 🌐 345 AI Providers — 152 Catalog-Marked Free

> **345 providers**, including **152 registered providers carrying `hasFree: true` discovery metadata**, plus **446 per-model free-budget catalog rows** and **54 recurring/keyless free-forever providers**. The provider flag and per-model budget catalog are distinct denominators; definitions and pool-deduped calculations are documented in the [Provider Reference](docs/reference/PROVIDER_REFERENCE.md) and [Free Tiers](docs/reference/FREE_TIERS.md).

### 🏢 Every major lab — through one endpoint

_OpenAI	_Anthropic	_Gemini	_{xAI Grok}	_DeepSeek	_Mistral
_Qwen	_{Meta Llama}	_Groq	_NVIDIA	_MiniMax	_Cohere
_Perplexity	_HuggingFace	_Together	_Fireworks	_Cloudflare	_Baidu

_{…and 328 more — every icon resolves live from the dashboard's provider catalog. 📖 [Provider Reference](docs/reference/PROVIDER_REFERENCE.md)}
### 🆓 Free Forever — $0, no card

OpenCode Zen _{DeepSeek V4, Nemotron 3 No token cap}	Kilo Code _{Auto-router, Tencent Hy3 Free forever}	Requesty _{GPT-OSS 120B, Nemotron Free forever}	SiliconFlow _{DeepSeek V3.2 / R1 Free tier}	Z.AI GLM _{GLM-4.7 / 4.5-Flash Free forever}	Baidu ERNIE _{ERNIE 4.0 Free forever}
Tencent Hunyuan _{Recurring uncapped catalog entry}	Pollinations _{GPT, Qwen, DeepSeek No key needed}	Cloudflare AI _{9 cataloged models 10K neurons/day}	Groq _{Recurring free pool 15M tokens/month}	Cerebras _{GLM 4.7, GPT-OSS 1M tokens/day}	OpenRouter _{:free models +$10 → higher RPM}

📖 Full machine-readable catalog → [`docs/reference/PROVIDER_REFERENCE.md`](docs/reference/PROVIDER_REFERENCE.md)

## 🖥️ Where OmniRoute Runs — Anywhere

> 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
🤖 VS Code Copilot Chat	install OmniCopilot extension	Every OmniRoute model in the native Copilot Chat picker — stable & Insiders
🛠️ From source	`npm install && npm run dev`	Hack on it, contribute

_{📖 [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)}

### 🧩 New: OmniRoute inside VS Code's native Copilot Chat

> 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 →	VS Code — stable & Insiders
🔓 Open VSX Registry	Install →	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). _{📖 [VS Code Copilot Chat guide](docs/guides/VSCODE-COPILOT.md) — setup, what the picker shows, dashboard-in-a-tab, troubleshooting}

## 🔒 Private & Local-First

_{📖 [Authorization](docs/architecture/AUTHZ_GUIDE.md) · [Guardrails](docs/security/GUARDRAILS.md) · [Compliance](docs/security/COMPLIANCE.md)}

## 🔌 Full CLI + A2A & MCP

> Beyond the server, OmniRoute is a **full command-line cockpit** with **85 top-level 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. _{📖 [Remote Mode](docs/guides/REMOTE-MODE.md)}

Animated terminal demoing the OmniRoute CLI — omniroute providers list, omniroute combo list and omniroute health — cycling over the 85-command top-level surface: 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 …

### 🤝 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 — 110 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 ``` _{📖 [MCP Server](docs/frameworks/MCP-SERVER.md) · [A2A Server](docs/frameworks/A2A-SERVER.md) · [Agent Protocols](docs/frameworks/AGENT_PROTOCOLS_GUIDE.md)}

## 🗜️ Save 15–95% Tokens — Automatically

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

OmniRoute compression pipeline: an illustrative 10,000-token client request passes through 12 composable engines — Session-Dedup, CCR, Lite, RTK, Responses Tool Output, Headroom, Relevance, Caveman, Aggressive, LLMLingua-2, Ultra and OmniGlyph — and can reach the provider at about 1,080 tokens in the documented stacked example. Structured content is protected by preservation guards and per-step fidelity gates; explicit lossy or experimental modes may transform eligible content.

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 **protected by default** through preservation guards and per-step fidelity checks; explicit lossy or experimental modes may transform eligible content. > **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) (⭐ 100K+), [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 protected by preservation guards and fidelity checks. Explicit lossy or experimental modes may transform eligible content. **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 technical recommendation in this example. 72% fewer tokens.** ✅ **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 recomendação técnica neste exemplo. ~70% menos tokens.** ✅
### 🎚️ 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: ; 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)

# ⚡ Quick Start

**1) Install & run** ```bash npm install -g 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).The image pins **`OMNIROUTE_MEMORY_MB=1024`**. That is enough for the dashboard and a light chat. **Coding agents** (`POST /v1/responses` from Claude Code, Codex, Grok, …) need a much larger V8 heap or the process `FATAL ERROR`s at ~12 GiB under two overlapping long contexts. Size the container above the heap (native buffers sit outside V8): | Workload | Heap (`-e OMNIROUTE_MEMORY_MB`) | Container (`--memory`) | | ----------------------------------- | ------------------------------- | ---------------------- | | Dashboard / light chat | `1024` (image default) | ≥2 g | | One coding agent | `8192` | ≥10 g | | Two concurrent long `/v1/responses` | `10240`–`12288` | ≥12–16 g | ```bash docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \ -e OMNIROUTE_MEMORY_MB=8192 --memory=10g \ -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest ``` Full table: [Docker Guide — runtime RAM](docs/guides/DOCKER_GUIDE.md#runtime-ram-for-coding-agents). > **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). **🥟 Bun** Standard `bun install` and global installation (`bun install -g omniroute`) are supported via Bun runtime detection: - **Built-in `bun:sqlite`**: OmniRoute uses Bun's built-in `bun:sqlite` driver when running under Bun, falling back to `better-sqlite3` on Node.js or `sql.js`. - **Automatic Webpack bundler selection**: Development (`bun run dev`) and production builds (`bun run build`) automatically detect Bun and disable Turbopack in favor of Webpack to prevent native V8 binding incompatibilities. - **Dedicated Bun Dockerfile**: Multi-stage `Dockerfile.bun` for native Bun production deployments (`docker build -f Dockerfile.bun -t omniroute:bun .`). ```bash # Install and run with Bun bun install bun run dev ``` **🛠️ 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. 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 -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.

# 🎬 OmniRoute in Action

## 📹 Video Guides

_{Dados do painel de cobertura, gerados em 2026-08-23 · YT: 809 | TT: 137 | IG: 124 · Frescor (dias): YT 0 · TT 20 · IG 21}

🎬 #1 — Instagram
_{nick_saraev — 1,628,910 views}

🎬 #2 — TikTok
_{milesreevesai — 620,400 views}

🎬 #3 — YouTube
_{Vaibhav Sisinty — 391,109 views}

🎬 #4 — YouTube Shorts
_{Nick Automates — 218,174 views}

🎬 #5 — TikTok
_{midudev — 177,800 views}

**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) — **391,109** | [Nick Automates — YouTube Shorts](https://www.youtube.com/shorts/fZIBK_4fKq8) — **218,174** | [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** | [Vaibhav Sisinty — YouTube](https://www.youtube.com/watch?v=NuNDpeZYQ28) — **141,410** | [Valency Labs — YouTube](https://www.youtube.com/watch?v=LkP6ocAoQkk) — **137,404** | [Asati — YouTube](https://www.youtube.com/watch?v=JjPtJcqwhqg) — **127,076** | Métricas de validação: **1,070 vídeos rastreados** · no YouTube, 450 longos e 359 Shorts; 239 itens estão fora de playlists · **7,467,359 visualizações conhecidas** · **639 perfis/canais**. Nos últimos 7 dias: 81 vídeos; nos últimos 30 dias: 530 (YT 448 · TT 53 · IG 29). > 🎬 **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.

# 📧 Community & Help > Everything in one place — follow the maintainer, chat with the community, or open an issue. | Channel | Where / how | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | 💼 **LinkedIn** — follow the maintainer | [linkedin.com/in/diegosouzapw](https://www.linkedin.com/in/diegosouzapw/) | | 🐙 **GitHub** — follow for releases & tips | [@diegosouzapw](https://github.com/diegosouzapw) | | 💬 **Discord** | [discord.gg/U47eFqAXCn](https://discord.gg/U47eFqAXCn) | | ✈️ **Telegram** | [t.me/omnirouteOficial](https://t.me/omnirouteOficial) | | 🟢 **WhatsApp — 🌍 Global** | [join the group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) | | 🟢 **WhatsApp — 🇧🇷 Brasil** | [entrar no grupo](https://chat.whatsapp.com/LTSpdFhXTxjH4R6CCNiKWz) | | 🌍 **Website** | [omniroute.online](https://omniroute.online) | | 📦 **Source code** | [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) | | 🐛 **Report a bug** | [open an issue](https://github.com/diegosouzapw/OmniRoute/issues) — attach `npm run system-info` output | | 🤝 **Contribute** | [CONTRIBUTING.md](CONTRIBUTING.md) · [Branching & Release Model](docs/ops/BRANCHING_MODEL.md) · pick a `good first issue` | | 💚 **Support the project** | [Ways to support ↑](#-support-omniroute) · [GitHub Sponsors](https://github.com/sponsors/diegosouzapw) |

---

## 🛠️ Tech Stack

Layer	Technology
Runtime	Node.js 22.x / 24.x LTS — `>=22.22.2 <23 \|\| >=24.0.0 <27`
Language	TypeScript 6.0 — TypeScript-first across `src/` and `open-sse/`; new explicit `any` is blocked by the ESLint quality gate
Framework	Next.js 16 + React 19 + Tailwind CSS 4
Database	better-sqlite3 (SQLite, WAL journaling) + LowDB (JSON legacy) — 120 domain modules, 160 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 & 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 — 36,000+ static `test`/`it` declarations across 5,085 tracked test/spec 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 · npm · Docker Hub

## 📖 Documentation

### 📘 Getting Started

Document	Description
User Guide	Providers, combos, CLI integration, deployment
Setup Guide	Full install methods, CLI tool configs, protocol setup, timeout tuning
CLI Tools Guide	Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot
Remote Mode	Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens
Claude Code Config	Point Claude Code at OmniRoute (local/remote) with `launch` + per-model profiles
Quick Start	3-step install → connect → configure

### 🔧 Operations & Deployment

Document	Description
Docker Guide	Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags
Podman Guide	Quadlet systemd integration, podman-compose, SELinux
VM Deployment	Complete guide: VM + nginx + Cloudflare setup
Fly.io Deployment	Deploy to Fly.io with persistent storage
Termux Guide	Run OmniRoute on Android via Termux
PWA Guide	Progressive Web App install, caching, architecture
Uninstall Guide	Clean removal for all install methods
Environment Config	Complete `.env` variables and references

### 🧠 Features & Architecture

Document	Description
Architecture	System architecture, data flow, and internals
Compression Guide	9-mode pipeline: off / lite / standard / aggressive / ultra / RTK / Responses Tool Output / OmniGlyph / stacked
RTK Compression	Command-output compression, filters, trust, verify, raw-output recovery
Compression Engines	Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces
Compression Rules Format	JSON rule-pack schemas for Caveman and RTK filters
Compression Language Packs	Language detection and Caveman rule-pack authoring
Resilience Guide	Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing
Auto-Combo Engine	15-factor scoring, mode packs, self-healing
Proxy Guide	3-level proxy system, 1proxy marketplace, registry CRUD
Free Tiers	Consolidated directory: 38 documented recurring pools / 446 cataloged free-tier entries
Features Gallery	Visual dashboard tour with screenshots
Codebase Documentation	Beginner-friendly codebase walkthrough

### 🤖 Protocols & APIs

Document	Description
API Reference	All endpoints with examples
OpenAPI Spec	OpenAPI 3.0 specification
MCP Server	110 MCP tools, IDE configs, Python/TS/Go clients
MCP Server Guide	MCP installation, transports, and tool reference
A2A Server	JSON-RPC 2.0 protocol, skills, streaming, task mgmt
A2A Server Guide	A2A agent card, tasks, skills, and streaming

### 📋 Project & Quality

Document	Description
Contributing	Development setup and guidelines
Branching & Release Model	Where PRs target (`release/*`), what `main` and tags mean
Changelog	Full per-version release history
Security Policy	Vulnerability reporting and security practices
i18n Guide	43-language support, translation workflow, RTL
Release Checklist	Pre-release validation steps
Coverage Plan	Test coverage strategy for 36,000+ static test declarations

# ⭐ 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.**

backryun _{🥇 219 GitHub-attributed commits · tied #1}	Paijo _{🥇 219 GitHub-attributed commits · tied #1}	R.D. & Randi _{🥉 108 GitHub-attributed commits}	Ravi Tharuma _{🏅 74 GitHub-attributed commits}	Chris Staley _{🏅 70 GitHub-attributed commits}	Dizzle _{🏅 69 GitHub-attributed commits}
Markus Hartung _{🏅 68 GitHub-attributed commits}	Jan Leon _{🏅 64 GitHub-attributed commits}	zenobit _{🏅 62 GitHub-attributed commits}	Bob Hou _{🏅 51 GitHub-attributed commits · tied #10}	Xiangzhe _{🏅 51 GitHub-attributed commits · tied #10}

_{Ranking snapshot: GitHub-attributed commits reported by the repository Contributors API for the v3.8.50 default branch on 2026-08-23. Bots, anonymous identities and the maintainer are excluded from this table; tied positions are retained.} > 🙏 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.

---
## 💖 Sponsors

A heartfelt thank-you to the people who fund OmniRoute out of their own pocket — every contribution keeps the project free, independent and moving.

Prof. Igor Morais
_{💛 Sponsor}

longtao
_{💛 Sponsor}

drewbitt
_{💛 Sponsor}

psylligent
_{💛 Sponsor}

pacocartones
_{💛 Sponsor}

_{… and others who prefer to stay private 💛} _{Public GitHub Sponsors revalidated on 2026-08-23; previously disclosed one-time donors remain listed, and private supporters stay anonymous.} 💖 Become a sponsor → — every dollar keeps OmniRoute free and independent.

## 👥 600+ Contributors

[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=635&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) _{Audited at reconciled v3.8.50 candidate aab9b946 on 2026-08-23: 635 normalized human Git identities — 403 appear as commit authors, including the maintainer, and another 232 appear only in explicit Co-authored-by trailers. Formula: all commits reachable from the candidate head; e-mails are case-normalized, and numeric, non-numeric and malformed numeric GitHub noreply variants encoding the same handle are joined. Bots, agents, service accounts and placeholder identities are excluded. No .mailmap exists, and ordinary same-name identities with different e-mails are deliberately not merged, so this is a conservative, reproducible Git-metadata census rather than a count of verified unique people or GitHub profiles.} ### 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 VERSION=x.y.z gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes ```

## 📊 Stars

## 🌍 StarMapper

## 🙏 Acknowledgments

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 verified from GitHub's GraphQL API on August 23, 2026 — go give these projects a star. Counts are a dated snapshot and will naturally change. ### 🧬 Lineage & gateway

Project	⭐	How it inspired OmniRoute
9router	26.1k	The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite.
CLIProxyAPI	48.4k	The Go implementation that inspired this JavaScript / TypeScript port.
LiteLLM	57.1k	The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing.
codex-chatgpt-web	1.4k	MIT source adapted into the vendored ChatGPT Web → Codex Responses bridge, including browser-session, response-framing, usage and web-search adapters.
free-claude-code	47.7k	Patterns ported into stream recovery, no-thinking aliases, fallback web search, sliding-window limits, log redaction and hardened launcher flows.
composer-api	323	Cursor Composer tool-choice, output-constraint and tool-commit patterns adapted into the native Cursor executor.
codex-multi-auth	457	Fresh-login and refresh-token rotation patterns ported into Codex OAuth reauthentication.
opencode-anthropic-auth	510	Claude Code-compatible transform defaults and billing-header behavior generalized into OmniRoute's config-driven bridge.
grok2api-merged	2	Its Grok model mappings, fake-TypeError Statsig generator, request and device defaults, and NDJSON response processor were materially adapted into OmniRoute's Grok Web executor.
TQZHR/grok2api	705	The principal transitive code source behind grok2api-merged; its model, header, payload, Statsig and processor implementations are preserved in the Grok Web lineage.
chenyme/grok2api	7.5k	The underlying MIT source for Grok payload and device defaults, the Statsig generator, and the `result.response` processor carried through TQZHR and grok2api-merged.
grok2api-pro	27	A transitive source credited by grok2api-merged for its proxy-pool layer; OmniRoute preserves that lineage notice but does not claim a proxy-pool port in its bounded Grok Web executor.
GrokProxy	50	Its cookie-authenticated Grok proxy and `result.response.token` streaming pattern informed OmniRoute's Grok Web transport.
GrokBridge	5	The original Grok Web implementation consulted its HTTP/browser upstream design; its direct HTTP path derives from GrokProxy, so no independent code port is claimed.
grok-web-api	14	Its Rust `ChatOptions` and response-envelope schemas informed OmniRoute's TypeScript Grok request and streaming-response types.

### 🗜️ Context & token compression — engines

Project	⭐	How it inspired OmniRoute
Caveman	100.5k	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	77.1k	High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline.
headroom	67.3k	Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern.
LLMLingua	6.6k	Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open `llmlingua` engine.
llmlingua-2-js	31	The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine.
Troglodita	40	PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar.
ponytail	108.6k	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).
i-have-adhd	23.4k	Its action-first, ADHD-friendly response style was adapted into OmniRoute's concise output style across five languages.

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

Project	⭐	How it inspired OmniRoute
TOON	25.2k	Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage.
GCF – Graph Compact Format	41	Its compact graph format and generic-profile design informed OmniRoute's tabular compaction and Headroom codec format.
gcf-typescript	4	The MIT TypeScript implementation directly vendored and extended as the Headroom generic-profile codec.
token-optimizer-mcp	494	Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine.
token-savior	1.1k	Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction.
token-saver	138	Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip.
token-optimizer	1.9k	"Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking.
TokenMizer	27	A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design.
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	113	MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction.
RepoMapper	197	Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration.
quiet-shell-mcp	4	Declarative shell-output reduction over MCP — validated our declarative bash-output compaction.
ts-morph	6.2k	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	63.9k	Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture.
Letta (MemGPT)	24.4k	Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model.
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	66	MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking. The upstream's complete license text is still under provenance review.
ProxyBridge	5.9k	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	6.5k	Open database of AI model specs, pricing and capabilities — synced natively into our model catalog.
React Flow / xyflow	38.1k	The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio.
LangGraph	40.3k	LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view.
Langfuse	33.6k	Its trace → span → generation observability model shaped our Compression Studio waterfall.
Kiali	3.6k	Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio.
lobe-icons	2.4k	AI/LLM brand logos that render the provider icons across our dashboard.
flag-icons	12.4k	Provides the MIT-licensed SVG flags used by the README language selector.

### 🛡️ Security

Project	⭐	How it inspired OmniRoute
awesome-secure-defaults	721	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
ClawRouter	6.6k	Inspired request deduplication, emergency zero-cost fallback, pluggable Auto-Combo strategies and multilingual intent classification.
Antigravity-Manager	30.6k	Its account-aware model remapping, executable-path validation and plan-label behavior informed OmniRoute's Antigravity runtime.
vscode-antigravity-cockpit	4.8k	Its compact quota-reset countdown format inspired the corresponding provider-limit display in OmniRoute.
AionUi	32.2k	Its ACP integrations inspired OmniRoute's automatic detection of installed CLI agents.
CodexBar	20.5k	Identified the Grok Build quota surface; OmniRoute then verified and corrected the live wire format independently.

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

**[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community. _{OmniRoute v3.8.50 · Node ≥22.22.2 · MIT License · omniroute.online}