https://github.com/diegosouzapw/omniroute

Never stop coding. Free AI gateway: one endpoint, 160+ providers (50+ free), connect Claude Code, Codex, Cursor, Cline & Copilot to FREE Claude/GPT/Gemini. RTK+Caveman stacked compression saves 15-95% tokens, smart auto-fallback, MCP/A2A, multimodal APIs, Desktop/PWA.
https://github.com/diegosouzapw/omniroute
a2a ai-agents ai-gateway anthropic claude claude-code cline codex copilot cursor deepseek free-ai gemini gemini-cli llm-gateway mcp openai openai-proxy qwen token-saver
Last synced: 3 days ago
JSON representation
Host: GitHub
URL: https://github.com/diegosouzapw/omniroute
Owner: diegosouzapw
License: mit
Created: 2026-02-13T12:38:31.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-05-23T07:25:16.000Z (7 days ago)
Last Synced: 2026-05-23T07:33:15.572Z (7 days ago)
Topics: a2a, ai-agents, ai-gateway, anthropic, claude, claude-code, cline, codex, copilot, cursor, deepseek, free-ai, gemini, gemini-cli, llm-gateway, mcp, openai, openai-proxy, qwen, token-saver
Language: TypeScript
Homepage: https://omniroute.online
Size: 99.3 MB
Stars: 5,174
Watchers: 20
Forks: 884
Open Issues: 75
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project

awesome-ChatGPT-repositories - OmniRoute - OmniRoute is an AI gateway for multi-provider LLMs: an OpenAI-compatible endpoint with smart routing, load balancing, retries, and fallbacks. Add policies, rate limits, caching, and observability for reliable, cost-aware inference. (The latest additions 🎉)
README

          







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




[![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)

[![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)



[![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/CLI-TOOLS.md`](docs/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/DOCKER_GUIDE.md) · [Desktop](electron/README.md) · [Termux](docs/TERMUX_GUIDE.md) · [PWA](docs/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) and [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 51K+).

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




### 📖 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_GUIDE.md) · [`RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md) · [`COMPRESSION_ENGINES.md`](docs/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

```

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






# 🎬 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/FREE_TIERS.md`](docs/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/PROXY_GUIDE.md`](docs/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/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/USER_GUIDE.md) · [API Reference](docs/API_REFERENCE.md) · [Environment Config](docs/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/TROUBLESHOOTING.md`](docs/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/USER_GUIDE.md)      | Providers, combos, CLI integration, deployment                                |

| [Setup Guide](docs/SETUP_GUIDE.md)    | Full install methods, CLI tool configs, protocol setup, timeout tuning        |

| [CLI Tools Guide](docs/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/DOCKER_GUIDE.md)                 | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |

| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md)         | Complete guide: VM + nginx + Cloudflare setup                  |

| [Fly.io Deployment](docs/FLY_IO_DEPLOYMENT_GUIDE.md) | Deploy to Fly.io with persistent storage                       |

| [Termux Guide](docs/TERMUX_GUIDE.md)                 | Run OmniRoute on Android via Termux                            |

| [PWA Guide](docs/PWA_GUIDE.md)                       | Progressive Web App install, caching, architecture             |

| [Uninstall Guide](docs/UNINSTALL.md)                 | Clean removal for all install methods                          |

| [Environment Config](docs/ENVIRONMENT.md)            | Complete `.env` variables and references                       |

### 🧠 Features & Architecture

| Document                                                         | Description                                                                   |

| ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |

| [Architecture](docs/ARCHITECTURE.md)                             | System architecture, data flow, and internals                                 |

| [Compression Guide](docs/COMPRESSION_GUIDE.md)                   | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked |

| [RTK Compression](docs/RTK_COMPRESSION.md)                       | Command-output compression, filters, trust, verify, raw-output recovery       |

| [Compression Engines](docs/COMPRESSION_ENGINES.md)               | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces                   |

| [Compression Rules Format](docs/COMPRESSION_RULES_FORMAT.md)     | JSON rule-pack schemas for Caveman and RTK filters                            |

| [Compression Language Packs](docs/COMPRESSION_LANGUAGE_PACKS.md) | Language detection and Caveman rule-pack authoring                            |

| [Resilience Guide](docs/RESILIENCE_GUIDE.md)                     | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing        |

| [Auto-Combo Engine](docs/AUTO-COMBO.md)                          | 6-factor scoring, mode packs, self-healing                                    |

| [Proxy Guide](docs/PROXY_GUIDE.md)                               | 3-level proxy system, 1proxy marketplace, registry CRUD                       |

| [Free Tiers](docs/FREE_TIERS.md)                                 | 25+ free API providers consolidated directory                                 |

| [Features Gallery](docs/FEATURES.md)                             | Visual dashboard tour with screenshots                                        |

| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md)         | Beginner-friendly codebase walkthrough                                        |

### 🤖 Protocols & APIs

| Document                                    | Description                                         |

| ------------------------------------------- | --------------------------------------------------- |

| [API Reference](docs/API_REFERENCE.md)      | All endpoints with examples                         |

| [OpenAPI Spec](docs/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/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/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/I18N.md)                     | 40+ language support, translation workflow, RTL |

| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps                    |

| [Coverage Plan](docs/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.




## 📄 License

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

---



**[⬆ Back to top](#-omniroute)** · Built with ❤️ for the open-source AI community.

_{OmniRoute v3.8.2 · Node ≥22.22.2 · MIT License · omniroute.online}
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/diegosouzapw/omniroute

Awesome Lists containing this project

README
