# 🚀 OmniRoute — The Free AI Gateway ### Never stop coding. Connect every AI tool to **177 providers** — **50+ free** — through one endpoint. **Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.**
**RTK + Caveman compression saves 15–95% tokens. Never hit limits.**
**~1.9B+ documented free tokens/month** — up to **~2.5B in your first month** with signup credits — aggregated across the free tiers, 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))
[![177 AI Providers](https://img.shields.io/badge/177-AI_Providers-6C5CE7?style=for-the-badge)](#-177-ai-providers--50-free) [![50+ Free](https://img.shields.io/badge/50%2B-Free_Tiers-00B894?style=for-the-badge)](#-177-ai-providers--50-free) [![1.9B+ Free Tokens/mo](https://img.shields.io/badge/1.9B%2B-Free_Tokens%2Fmo-00B894?style=for-the-badge)](docs/reference/FREE_TIERS.md) [![Token Savings](https://img.shields.io/badge/up_to_95%25-Token_Savings-E17055?style=for-the-badge)](#%EF%B8%8F-save-1595-tokens--automatically) [![14 Strategies](https://img.shields.io/badge/14-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship) [![$0 to start](https://img.shields.io/badge/%240-To_Start-FDCB6E?style=for-the-badge&logoColor=black)](#-quick-start)
### 💬 Join the community on Discord [![Join our Discord](https://img.shields.io/badge/Join_our_Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/hmexnhgE) **Questions, provider tips, roadmap & support → [discord.gg/hmexnhgE](https://discord.gg/hmexnhgE)**

[![npm](https://img.shields.io/npm/v/omniroute?logo=npm&style=flat-square)](https://www.npmjs.com/package/omniroute) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE) [![Node](https://img.shields.io/badge/node-%E2%89%A522.22.2-brightgreen?style=flat-square)](package.json) [![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)

[![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) ![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) [![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online)

[**🚀 Quick Start**](#-quick-start) • [**🎯 Combos**](#-combos--the-flagship) • [**🌐 Providers**](#-177-ai-providers--50-free) • [**🔌 CLI & MCP**](#-full-cli--a2a--mcp) • [**🗜️ Compression**](#%EF%B8%8F-save-1595-tokens--automatically) • [**🌍 Website**](https://omniroute.online) • [**💬 WhatsApp 🌍**](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) • [**💬 WhatsApp 🇧🇷**](https://chat.whatsapp.com/CeGCxdFzqBe5Uki288wOvf) [💥 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)

🌐 Available in 40+ languages

🇺🇸	🇧🇷	🇪🇸	🇫🇷	🇮🇹	🇷🇺	🇨🇳	🇩🇪	🇯🇵	🇰🇷	🇮🇳
🇹🇭	🇻🇳	🇮🇩	🇲🇾	🇵🇭	🇸🇦	🇮🇱	🇦🇿	🇺🇦	🇵🇱	🇨🇿
🇳🇱	🇧🇬	🇩🇰	🇫🇮	🇳🇴	🇸🇪	🇭🇺	🇷🇴	🇸🇰	🇵🇹

# 💥 The Promise

> One endpoint. **177 providers.** Never stop building — and let OmniRoute pick the cheapest one that works.

🚫 Never hit limits _{Auto-fallback across 177 providers in milliseconds. Quota out? Next provider takes over — zero downtime.}	💸 Save up to 95% tokens _{RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions).}	🆓 $0 to start _{50+ providers with a free tier, 11 free forever (Kiro, Qoder, Pollinations, LongCat…). No card needed.}
🔌 Every tool works _{16+ coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config.}	🧩 One endpoint _{OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at /v1 and it just works.}	🛡️ Production-grade _{Circuit breakers, TLS stealth, MCP (37 tools), A2A, memory, guardrails, evals. 4,690+ tests.}

# 🤔 Why OmniRoute?

> 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 |

``` ┌──────────────────────────────────────────────────────────┐ │ Your IDE / CLI (Claude Code, Cursor, Cline…) │ └─────────────────────────┬──────────────────────────────────┘ │ http://localhost:20128/v1 ▼ ┌──────────────────────────────────────────────────────────┐ │ OmniRoute — Smart Router │ │ RTK + Caveman compression · 14 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 ```

# 🎯 Combos — The Flagship

> 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 — 14 routing strategies | Goal | Strategy / combo | | --------------------------------------- | -------------------------------------------------- | | 🥇 Drain my subscription before paying | `priority` / `fill-first` | | ⚖️ Spread load across accounts | `round-robin` · `weighted` · `p2c` · `least-used` | | 💸 Always cheapest viable model | `cost-optimized` · `auto/cheap` | | 🧠 Hand off long context between models | `context-relay` · `context-optimized` | | 🎲 Randomized / privacy routing | `random` · `strict-random` | | 🤖 Just make it smart | `auto` (9-factor scoring) · `lkgp` · `reset-aware` | _{The Auto-Combo engine scores every candidate on **9 factors** (health, quota, cost, latency, success rate, freshness…) — see [`docs/routing/AUTO-COMBO.md`](docs/routing/AUTO-COMBO.md).} ## ### 🧱 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 ``` _{📖 [Auto-Combo Engine](docs/routing/AUTO-COMBO.md) · [Resilience Guide](docs/architecture/RESILIENCE_GUIDE.md)}

# 🏆 What Sets OmniRoute Apart

| Feature | OmniRoute | Other routers | | -------------------------------------- | ----------------------------------------------------------- | ------------- | | 🌐 Providers | **177** | 20–100 | | 🆓 Free providers | **50+ (11 free forever)** | 1–5 | | 🔀 Routing strategies | **14** (priority, weighted, cost-optimized, context-relay…) | 1–3 | | 🗜️ Token compression | **RTK + Caveman stacked (15–95%)** | None / 20–40% | | 🧰 Built-in MCP server | **37 tools, 3 transports, 13 scopes** | Rare | | 🤝 A2A agent protocol | **5 skills, JSON-RPC 2.0** | None | | 🧠 Memory (FTS5 + vector) | **Yes** | Rare | | 🛡️ Guardrails (PII, injection, vision) | **Yes** | Rare | | ☁️ Cloud agents | **Codex, Devin, Jules** | None | | 🥷 TLS fingerprint stealth | **JA3/JA4 via wreq-js** | None | | 🖥️ Multi-platform | **Web · Desktop · Termux · PWA** | Web only | | 🌍 i18n | **40+ locales** | 0–4 | _{📊 Detailed comparison vs LiteLLM, OpenRouter & Portkey → [`docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md`](docs/comparison/OMNIROUTE_VS_ALTERNATIVES.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	Gemini CLI	Cursor	Copilot	Continue
OpenCode	Kilo Code	Droid	OpenClaw	Kiro	Command

＋ also works with · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · any OpenAI-compatible tool

_{📖 Per-tool setup for all 16+ tools → [`docs/reference/CLI-TOOLS.md`](docs/reference/CLI-TOOLS.md) · 🧩 OpenCode plugin → [`@omniroute/opencode-provider`](https://www.npmjs.com/package/@omniroute/opencode-provider)}

# 🌐 177 AI Providers — 50+ Free

> The most complete catalog of any open-source router: **177 providers**, **50+ with a free tier**, **11 free forever**.

### 🆓 Free Forever — $0, no card

_{GPT-5, Claude, Gemini $100 free credits}	_{Kimi-K2, DeepSeek-R1 Unlimited FREE}	_{GPT-5, Claude, Llama 4 No key needed}	_{Flash-Lite 50M tokens/day 🔥}
_{50+ models 10K neurons/day}	_{gemini-3-flash 180K/mo free}	_{129 models ~40 RPM free}	_{Qwen3 235B 1M tokens/day}

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

# 🔒 Private & Local-First

> 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. _{📖 [Authorization](docs/architecture/AUTHZ_GUIDE.md) · [Guardrails](docs/security/GUARDRAILS.md) · [Compliance](docs/security/COMPLIANCE.md)}

# 🔌 Full CLI + A2A & MCP

> OmniRoute isn't just a server — it's a **full command-line cockpit** with **60+ 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 ```

`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** 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 — **37 tools**, 13 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, 5 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 ``` _{📖 [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

> **Why use many token when few token do trick?** Every request passes through OmniRoute's compression pipeline **transparently** — no client changes. It stacks ideas from [RTK](https://github.com/rtk-ai/rtk), [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 51K+), and [Troglodita](https://github.com/leninejunior/troglodita) (PT-BR). | 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.** ✅
### 📖 How it works — pipeline, architecture & savings math ``` Client (10,000 tok) ──▶ OmniRoute Compression (7 options) ──▶ 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. Auto-trigger compression by token threshold, or assign a compression pipeline per routing combo. 📖 [`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 ``` 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 unlimited) 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.
## 📦 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 install -g omniroute && pnpm approve-builds -g && 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.

# 🎬 OmniRoute in Action

🇧🇷 Português
_{Guia completo}

🇺🇸 English
_{Complete walkthrough}

🇷🇺 Русский
_{Полное руководство}

> 🎬 **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.

# 📚 Explore More

💰 Pricing at a glance & the $0 Free Stack (11 providers)

| 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-Flash-Lite | 50M tokens/day 🔥 | | **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.

🎯 Use Cases — ready-made combo playbooks

**$0 forever:** ``` 1. kr/claude-sonnet-4.5 (Kiro — unlimited) 2. if/kimi-k2-thinking (Qoder — unlimited) 3. pol/gpt-5 (Pollinations — no key) 4. lc/longcat-flash-lite (50M tok/day backup) 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.

🌍 Bypass geo-blocks — 3-level proxy + stealth

🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 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)

✨ Full feature list — 30+ capabilities (memory, evals, observability)

**Routing:** 14 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 (37 tools, 3 transports, 13 scopes) · A2A (JSON-RPC 2.0, SSE, skills) · ACP · cloud agents (Codex, Devin, Jules). **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 `skills/omniroute/SKILL.md`. 10 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)

📖 Setup, env vars & FAQ

| 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?** Yes — Kiro, Qoder, Pollinations, LongCat, Cloudflare. No catch. **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 177 providers. 📖 [User Guide](docs/guides/USER_GUIDE.md) · [API Reference](docs/reference/API_REFERENCE.md) · [Environment Config](docs/reference/ENVIRONMENT.md)

🐛 Troubleshooting

| 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 `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24 <25` | 🐛 **Reporting a bug?** Run `npm run system-info` and attach `system-info.txt`. 📖 [`docs/guides/TROUBLESHOOTING.md`](docs/guides/TROUBLESHOOTING.md)

📸 Dashboard screenshots

| Page | Screenshot | Page | Screenshot | | ---------- | ------------------------------------------------- | ---------- | --------------------------------------------- | | Providers | ![Providers](docs/screenshots/01-providers.png) | Combos | ![Combos](docs/screenshots/02-combos.png) | | Analytics | ![Analytics](docs/screenshots/03-analytics.png) | Health | ![Health](docs/screenshots/04-health.png) | | Translator | ![Translator](docs/screenshots/05-translator.png) | Settings | ![Settings](docs/screenshots/06-settings.png) | | CLI Tools | ![CLI Tools](docs/screenshots/07-cli-tools.png) | Usage Logs | ![Usage](docs/screenshots/08-usage.png) |

# 📧 Support & Community > 💬 **Join our WhatsApp groups** — get help, share tips, stay updated: > · [**🌍 International**](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) · [**🇧🇷 Português**](https://chat.whatsapp.com/CeGCxdFzqBe5Uki288wOvf) - 🌍 **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`

---

## 🛠️ Tech Stack

- **Runtime**: Node.js 20.20.2+, 22.22.2+, or 24.x LTS (24 LTS recommended) - **Language**: TypeScript 5.9 — **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 (**4,690+ test cases** across 517 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

## 📖 Documentation

### 📘 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 | | [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) | 6-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/reference/openapi.yaml) | OpenAPI 3.0 specification | | [MCP Server](open-sse/mcp-server/README.md) | 29 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 | | [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 4,690+ test suite |

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

oyi77
_{🥇 190 commits • +72K lines}
_{Analytics engine, SQL aggregations,
proxy marketplace, test coverage}

Chris Staley
_{🥈 72 commits • +5.7K lines}
_{SSE stream hardening, Responses API,
Gemini pagination, test regression fixes}

zenobit
_{🥉 62 commits • +24K lines}
_{CI/CD pipeline, i18n for 33 languages,
Void Linux package, platform fixes}

R.D. & Randi
_{🏅 107 commits • +28K lines}
_{Endpoints page, tunnel integrations,
Docker workflows, A2A status, compression UI}

benzntech
_{🏅 20 commits • +7.5K lines}
_{Electron desktop app, auto-updater,
release build workflows, cross-platform CI}

> 🙏 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.

---

## 👥 Contributors

[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](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 ```

## 📊 Stars

## 🌍 StarMapper

## 🙏 Acknowledgments

Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** — the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite. Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** by **[router-for-me](https://github.com/router-for-me)** — the original Go implementation that inspired this JavaScript port. Special thanks to **[Caveman](https://github.com/JuliusBrussee/caveman)** by **[JuliusBrussee](https://github.com/JuliusBrussee)** (⭐ 51K+) — the viral "why use many token when few token do trick" project whose caveman-speak compression philosophy inspired OmniRoute's standard compression mode and 30+ filler/condensation regex rules. Special thanks to **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)** by **[RTK AI](https://github.com/rtk-ai)** — the high-performance command-output compression project whose terminal, build, test, git, and tool-output filtering model inspired OmniRoute's RTK engine, JSON filter DSL, raw-output recovery, and stacked RTK → Caveman compression pipeline. Special thanks to **[Troglodita](https://github.com/leninejunior/troglodita)** by **[Lenine Júnior](https://github.com/leninejunior)** — the PT-BR token compression project ("por que gastar muitos tokens quando poucos resolve?") whose Portuguese-native rules power OmniRoute's pt-BR language pack: pleonasm reduction, filler removal tuned for Brazilian Portuguese grammar, and technical abbreviations for the dev BR community.
## 💰 Free-Token Budget — see exactly how much free inference you have 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 **50+ provider pools / 530 models** into one honest number and shows it live on the dashboard (`/dashboard/free-tiers`). - **~1.9B free tokens / month** (steady) — and **up to ~2.5B 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. (The naïve per-model sum would read ~8B; we don't publish that.) - **Per-model breakdown**, **live used / remaining** for the current month, and a **ToS flag** for the 19 providers whose terms don't permit proxying. ![Free-Tier Budget card (preview mockup)](docs/screenshots/free-tier-budget-card.svg) > Preview mockup — a real screenshot lands once the `/dashboard/free-tiers` page is validated. Full methodology (pool dedupe, credit tiers, the 19 ToS-restricted providers): **[docs/reference/FREE_TIERS.md](docs/reference/FREE_TIERS.md)**.
## 📄 License MIT License - see [LICENSE](LICENSE) for details. ---

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