mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-04 22:32:12 +03:00
6424c82570
Refresh the compression docs and README to describe the default stacked pipeline in terms of eligible-context savings instead of the older generic token-saving range. Add upstream RTK and Caveman benchmark references, explain the multiplicative savings math behind the stacked default, and update feature summaries plus package metadata to match the revised positioning.
1522 lines
82 KiB
Markdown
1522 lines
82 KiB
Markdown
<div align="center">
|
|
|
|
# 🚀 OmniRoute — The Free AI Gateway
|
|
|
|
### Never stop coding. Save 15-95% eligible tokens with RTK+Caveman compression + auto-fallback to **FREE & low-cost AI models**.
|
|
|
|
_The most complete open-source AI proxy — **one endpoint**, **160+ providers**, **13 routing strategies**, zero downtime. Multi-platform: **Web**, **Desktop (Electron)**, **Mobile (PWA + Termux)**. Fully extensible via **MCP Server (37 tools)**, **A2A Protocol**, and **Memory/Skills** systems. Available in **40+ languages**._
|
|
|
|
**Chat Completions • Responses API • Embeddings • Image Generation • Video • Music • Audio Speech/Transcription • Reranking • Moderations • Web Search • MCP Server • A2A Protocol • 4,600+ Tests • 100% TypeScript**
|
|
|
|
<br/>
|
|
|
|
<a href="https://agentrouter.org/register?aff=70LM">
|
|
<img src="https://img.shields.io/badge/🎁_GET_$100_FREE_AI_CREDITS-AgentRouter_(no_card_needed)-ff6600?style=for-the-badge&labelColor=1a1a2e&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDIgNy41bDEwIDUuNSAxMC01LjVMMTIgMnpNMiAxNy41bDEwIDUuNSAxMC01LjVMMTIgMTIgMiAxNy41eiIvPjwvc3ZnPg==" alt="Get $100 Free AI Credits" height="40"/>
|
|
</a>
|
|
|
|
<sub>🔥 <b>Limited offer:</b> Sign up at <a href="https://agentrouter.org/register?aff=70LM"><b>AgentRouter</b></a> and get <b>$100 in free AI credits</b></br> Access GPT-5, Claude, Gemini, DeepSeek & 100+ models. No credit card required. <a href="https://agentrouter.org/register?aff=70LM"><b>Claim your credits →</b></a></sub>
|
|
|
|
<br/>
|
|
|
|
<a href="https://trendshift.io/repositories/23589" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23589" alt="diegosouzapw%2FOmniRoute | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
|
|
|
[🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [🗜️ Compression](#%EF%B8%8F-prompt-compression--save-15-95-eligible-tokens-automatically) • [💰 Pricing](#-pricing-at-a-glance) • [🎯 Use Cases](#-use-cases--ready-made-combo-playbooks) • [🌍 Proxy](#-bypass-geographic-blocks--use-ai-from-any-country) • [❓ FAQ](#-frequently-asked-questions) • [📖 Docs](#-documentation) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
<div align="">
|
|
|
|
🌐 **Available in:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md)
|
|
|
|
</div>
|
|
|
|
<div align="center">
|
|
|
|
[](https://www.npmjs.com/package/omniroute)
|
|
|
|
|
|
|
|
|
|
[](https://hub.docker.com/r/diegosouzapw/omniroute)
|
|
|
|
|
|
[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
|
|
|
|
<!-- Community & Social -->
|
|
|
|
[](https://github.com/diegosouzapw)
|
|
[](https://github.com/diegosouzapw)
|
|
[](https://omniroute.online)
|
|
[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 🖼️ Main Dashboard
|
|
|
|
<div align="center">
|
|
<img src="./docs/screenshots/MainOmniRoute.png" alt="OmniRoute Dashboard" width="800"/>
|
|
</div>
|
|
|
|
---
|
|
|
|
## 📸 Dashboard Preview
|
|
|
|
<details>
|
|
<summary><b>Click to see dashboard screenshots</b></summary>
|
|
|
|
| Page | Screenshot |
|
|
| -------------- | ------------------------------------------------- |
|
|
| **Providers** |  |
|
|
| **Combos** |  |
|
|
| **Analytics** |  |
|
|
| **Health** |  |
|
|
| **Translator** |  |
|
|
| **Settings** |  |
|
|
| **CLI Tools** |  |
|
|
| **Usage Logs** |  |
|
|
| **Endpoints** |  |
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
### 🤖 Free AI Provider for your favorite coding agents
|
|
|
|
_Connect any AI-powered IDE or CLI tool through OmniRoute — free API gateway for unlimited coding._
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/openclaw/openclaw">
|
|
<img src="./public/providers/openclaw.png" alt="OpenClaw" width="48"/><br/>
|
|
<b>OpenClaw</b>
|
|
</a><br/>
|
|
<sub>⭐ 205K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/HKUDS/nanobot">
|
|
<img src="./public/providers/nanobot.png" alt="NanoBot" width="48"/><br/>
|
|
<b>NanoBot</b>
|
|
</a><br/>
|
|
<sub>⭐ 20.9K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/sipeed/picoclaw">
|
|
<img src="./public/providers/picoclaw.jpg" alt="PicoClaw" width="48"/><br/>
|
|
<b>PicoClaw</b>
|
|
</a><br/>
|
|
<sub>⭐ 14.6K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/zeroclaw-labs/zeroclaw">
|
|
<img src="./public/providers/zeroclaw.png" alt="ZeroClaw" width="48"/><br/>
|
|
<b>ZeroClaw</b>
|
|
</a><br/>
|
|
<sub>⭐ 9.9K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/nearai/ironclaw">
|
|
<img src="./public/providers/ironclaw.png" alt="IronClaw" width="48"/><br/>
|
|
<b>IronClaw</b>
|
|
</a><br/>
|
|
<sub>⭐ 2.1K</sub>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/anomalyco/opencode">
|
|
<img src="./public/providers/opencode.svg" alt="OpenCode" width="48"/><br/>
|
|
<b>OpenCode</b>
|
|
</a><br/>
|
|
<sub>⭐ 106K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/openai/codex">
|
|
<img src="./public/providers/codex.png" alt="Codex CLI" width="48"/><br/>
|
|
<b>Codex CLI</b>
|
|
</a><br/>
|
|
<sub>⭐ 60.8K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/anthropics/claude-code">
|
|
<img src="./public/providers/claude.png" alt="Claude Code" width="48"/><br/>
|
|
<b>Claude Code</b>
|
|
</a><br/>
|
|
<sub>⭐ 67.3K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/google-gemini/gemini-cli">
|
|
<img src="./public/providers/gemini-cli.png" alt="Gemini CLI" width="48"/><br/>
|
|
<b>Gemini CLI</b>
|
|
</a><br/>
|
|
<sub>⭐ 94.7K</sub>
|
|
</td>
|
|
<td align="center" width="110">
|
|
<a href="https://github.com/Kilo-Org/kilocode">
|
|
<img src="./public/providers/kilocode.png" alt="Kilo Code" width="48"/><br/>
|
|
<b>Kilo Code</b>
|
|
</a><br/>
|
|
<sub>⭐ 15.5K</sub>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<sub>📡 All agents connect via <code>http://localhost:20128/v1</code> or <code>http://cloud.omniroute.online/v1</code> — one config, unlimited models and quota</sub>
|
|
|
|
---
|
|
|
|
## 📺 OmniRoute in Action — Video Guides
|
|
|
|
<div align="center">
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="320">
|
|
<a href="https://www.youtube.com/watch?v=Rxdc36yUyOQ">
|
|
<img src="https://img.youtube.com/vi/Rxdc36yUyOQ/maxresdefault.jpg" alt="OmniRoute — Guia em Português" width="300"/>
|
|
</a><br/>
|
|
<b>🇧🇷 Português</b><br/>
|
|
<sub>Guia completo do OmniRoute</sub>
|
|
</td>
|
|
<td align="center" width="320">
|
|
<a href="https://www.youtube.com/watch?v=CMzyOiUyEVc">
|
|
<img src="https://img.youtube.com/vi/CMzyOiUyEVc/maxresdefault.jpg" alt="OmniRoute — English Guide" width="300"/>
|
|
</a><br/>
|
|
<b>🇺🇸 English</b><br/>
|
|
<sub>Complete OmniRoute walkthrough</sub>
|
|
</td>
|
|
<td align="center" width="320">
|
|
<a href="https://www.youtube.com/watch?v=il_5Ii6v4-Y">
|
|
<img src="https://img.youtube.com/vi/il_5Ii6v4-Y/maxresdefault.jpg" alt="OmniRoute — Руководство на русском" width="300"/>
|
|
</a><br/>
|
|
<b>🇷🇺 Русский</b><br/>
|
|
<sub>Полное руководство по OmniRoute</sub>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
</div>
|
|
|
|
> 🎬 **Made a video about OmniRoute?** We'd love to feature it here! Open an [issue](https://github.com/diegosouzapw/OmniRoute/issues/new) or [discussion](https://github.com/diegosouzapw/OmniRoute/discussions) with the link and we'll add it to this showcase.
|
|
|
|
---
|
|
|
|
## 🤔 Why OmniRoute?
|
|
|
|
**Stop wasting money, tokens and hitting limits:**
|
|
|
|
❌ Subscription quota expires unused every month
|
|
❌ Rate limits stop you mid-coding
|
|
❌ Tool outputs (`git diff`, `grep`, `ls`...) burn tokens fast
|
|
❌ Expensive APIs ($20-50/month per provider)
|
|
❌ Manual switching between providers
|
|
❌ Each provider has a different API format
|
|
❌ AI providers blocked in your country
|
|
|
|
**OmniRoute solves all of this:**
|
|
|
|
✅ **Prompt Compression** — auto-compress prompts & tool outputs, save 15-95% eligible tokens per request with RTK+Caveman stacked mode
|
|
✅ **Maximize subscriptions** — track quota, use every bit before reset
|
|
✅ **Auto fallback** — Subscription → API Key → Cheap → Free, zero downtime
|
|
✅ **Multi-account** — round-robin between accounts per provider
|
|
✅ **Format translation** — OpenAI ↔ Claude ↔ Gemini ↔ Responses API, any tool works
|
|
✅ **3-level proxy** — bypass geo-blocks with global, per-provider, and per-key proxies
|
|
✅ **10 multi-modal APIs** — chat, images, video, music, audio, search in one endpoint
|
|
✅ **MCP + A2A** — 29 MCP tools + agent-to-agent protocol, production-ready
|
|
✅ **Universal** — works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool
|
|
|
|
---
|
|
|
|
## 📧 Support
|
|
|
|
> 💬 **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Get help, share tips, and stay updated.
|
|
|
|
- **Website**: [omniroute.online](https://omniroute.online)
|
|
- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
|
|
- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
|
- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
|
|
- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue`
|
|
- **Original Project**: [9router by decolua](https://github.com/decolua/9router)
|
|
|
|
### 🐛 Reporting a Bug?
|
|
|
|
When opening an issue, please run the system-info command and attach the generated file:
|
|
|
|
```bash
|
|
npm run system-info
|
|
```
|
|
|
|
This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages — everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue.
|
|
|
|
---
|
|
|
|
## 🛠️ Supported CLI Tools
|
|
|
|
OmniRoute works seamlessly with **16+ AI coding tools** — one config, all tools:
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="110"><b>Claude Code</b><br/><sub>Anthropic</sub></td>
|
|
<td align="center" width="110"><b>Codex CLI</b><br/><sub>OpenAI</sub></td>
|
|
<td align="center" width="110"><b>Gemini CLI</b><br/><sub>Google</sub></td>
|
|
<td align="center" width="110"><b>Cursor</b><br/><sub>IDE</sub></td>
|
|
<td align="center" width="110"><b>OpenClaw</b><br/><sub>CLI</sub></td>
|
|
<td align="center" width="110"><b>Antigravity</b><br/><sub>VS Code</sub></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="110"><b>Cline</b><br/><sub>Extension</sub></td>
|
|
<td align="center" width="110"><b>Continue</b><br/><sub>Extension</sub></td>
|
|
<td align="center" width="110"><b>Kilo Code</b><br/><sub>Extension</sub></td>
|
|
<td align="center" width="110"><b>Kiro</b><br/><sub>AWS IDE</sub></td>
|
|
<td align="center" width="110"><b>OpenCode</b><br/><sub>CLI</sub></td>
|
|
<td align="center" width="110"><b>Droid</b><br/><sub>CLI</sub></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="110"><b>AMP</b><br/><sub>CLI</sub></td>
|
|
<td align="center" width="110"><b>Copilot</b><br/><sub>GitHub</sub></td>
|
|
<td align="center" width="110"><b>Windsurf</b><br/><sub>IDE</sub></td>
|
|
<td align="center" width="110"><b>Hermes</b><br/><sub>CLI</sub></td>
|
|
<td align="center" width="110"><b>Qwen CLI</b><br/><sub>Alibaba</sub></td>
|
|
<td align="center" width="110"><b>Custom</b><br/><sub>Any tool</sub></td>
|
|
</tr>
|
|
</table>
|
|
|
|
📖 Full setup for each tool: [`docs/CLI-TOOLS.md`](docs/CLI-TOOLS.md)
|
|
|
|
---
|
|
|
|
## 🌐 Supported Providers — 160+
|
|
|
|
### 🔐 OAuth Providers
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="130"><b>Claude Code</b><br/><sub>Anthropic OAuth</sub></td>
|
|
<td align="center" width="130"><b>Antigravity</b><br/><sub>Google OAuth</sub></td>
|
|
<td align="center" width="130"><b>Codex</b><br/><sub>OpenAI OAuth</sub></td>
|
|
<td align="center" width="130"><b>GitHub Copilot</b><br/><sub>GitHub OAuth</sub></td>
|
|
<td align="center" width="130"><b>Cursor</b><br/><sub>Cursor OAuth</sub></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="130"><b>Kimi Coding</b><br/><sub>Moonshot OAuth</sub></td>
|
|
<td align="center" width="130"><b>Kilo Code</b><br/><sub>Kilo OAuth</sub></td>
|
|
<td align="center" width="130"><b>Cline</b><br/><sub>Cline OAuth</sub></td>
|
|
<td align="center" colspan="2"></td>
|
|
</tr>
|
|
</table>
|
|
|
|
### 🆓 Free Providers (No Cost)
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="160"><b>🟢 Kiro AI</b><br/><sub>Claude Sonnet/Haiku<br/>Unlimited FREE</sub></td>
|
|
<td align="center" width="160"><b>🟢 Qoder AI</b><br/><sub>Kimi-K2, DeepSeek-R1<br/>Unlimited FREE</sub></td>
|
|
<td align="center" width="160"><b>🟢 Pollinations</b><br/><sub>GPT-5, Claude, Llama 4<br/>No API key needed</sub></td>
|
|
<td align="center" width="160"><b>🟢 Qwen Code</b><br/><sub>Qwen3 Coder Plus<br/>Unlimited FREE</sub></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="160"><b>🟢 LongCat AI</b><br/><sub>Flash-Lite<br/>50M tokens/day</sub></td>
|
|
<td align="center" width="160"><b>🟢 Cloudflare AI</b><br/><sub>50+ models<br/>10K neurons/day</sub></td>
|
|
<td align="center" width="160"><b>🟢 Puter AI</b><br/><sub>GPT-4.1, Claude<br/>Rate-limited free</sub></td>
|
|
<td align="center" width="160"><b>🟢 NVIDIA NIM</b><br/><sub>Llama, Mistral<br/>1K req/day free</sub></td>
|
|
</tr>
|
|
</table>
|
|
|
|
### 🔑 API Key Providers (120+)
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="110"><b>OpenAI</b></td>
|
|
<td align="center" width="110"><b>Anthropic</b></td>
|
|
<td align="center" width="110"><b>Gemini</b></td>
|
|
<td align="center" width="110"><b>DeepSeek</b></td>
|
|
<td align="center" width="110"><b>Groq</b></td>
|
|
<td align="center" width="110"><b>xAI (Grok)</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="110"><b>Mistral</b></td>
|
|
<td align="center" width="110"><b>OpenRouter</b></td>
|
|
<td align="center" width="110"><b>GLM</b></td>
|
|
<td align="center" width="110"><b>Kimi</b></td>
|
|
<td align="center" width="110"><b>MiniMax</b></td>
|
|
<td align="center" width="110"><b>Fireworks</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="110"><b>Together AI</b></td>
|
|
<td align="center" width="110"><b>Cerebras</b></td>
|
|
<td align="center" width="110"><b>Cohere</b></td>
|
|
<td align="center" width="110"><b>NVIDIA</b></td>
|
|
<td align="center" width="110"><b>Perplexity</b></td>
|
|
<td align="center" width="110"><b>SiliconFlow</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="110"><b>Nebius</b></td>
|
|
<td align="center" width="110"><b>HuggingFace</b></td>
|
|
<td align="center" width="110"><b>DeepInfra</b></td>
|
|
<td align="center" width="110"><b>SambaNova</b></td>
|
|
<td align="center" width="110"><b>Vertex AI</b></td>
|
|
<td align="center" width="110"><b>Azure OpenAI</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="110"><b>AWS Bedrock</b></td>
|
|
<td align="center" width="110"><b>Snowflake</b></td>
|
|
<td align="center" width="110"><b>Databricks</b></td>
|
|
<td align="center" width="110"><b>Venice.ai</b></td>
|
|
<td align="center" width="110"><b>AI21 Labs</b></td>
|
|
<td align="center" width="110"><b>Meta Llama</b></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<details>
|
|
<summary><b>...and 90+ more providers</b></summary>
|
|
|
|
Alibaba · Amazon Q · AssemblyAI · Baidu Qianfan · Baseten · Black Forest Labs · Blackbox · Brave Search · Bytez · CablyAI · Cartesia · ChatGPT Web · Chutes.ai · Clarifai · Codestral · CrofAI · DataRobot · Deepgram · ElevenLabs · Empower · Exa Search · Fal.ai · Featherless AI · FenayAI · FriendliAI · Galadriel · GigaChat · GitLab Duo · GLHF Chat · GoAPI · Heroku AI · Hyperbolic · IBM watsonx · Inference.net · Inworld · Jina AI · Kilo Gateway · Lambda AI · LaoZhang · Linkup Search · LlamaGate · Maritalk · Modal · Moonshot AI · Morph · Muse Spark · NanoBanana · NanoGPT · NLP Cloud · Nous Research · Novita AI · nScale · OCI · Ollama Cloud · OVHcloud · PiAPI · PlayHT · Poe · Predibase · PublicAI · Qwen Code · Recraft · Reka · Runway · SAP · Scaleway · SearchAPI · SearXNG · Serper · Stability AI · Synthetic · Tavily · TheB.AI · Topaz · Upstage · v0 (Vercel) · Vercel AI Gateway · Volcengine · Voyage AI · W&B Inference · Xiaomi MiMo · You.com · Z.AI · + OpenAI/Anthropic-compatible custom endpoints
|
|
|
|
</details>
|
|
|
|
### 🏠 Self-Hosted
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="130"><b>LM Studio</b></td>
|
|
<td align="center" width="130"><b>Ollama</b></td>
|
|
<td align="center" width="130"><b>vLLM</b></td>
|
|
<td align="center" width="130"><b>Llamafile</b></td>
|
|
<td align="center" width="130"><b>Docker Model Runner</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="130"><b>NVIDIA Triton</b></td>
|
|
<td align="center" width="130"><b>XInference</b></td>
|
|
<td align="center" width="130"><b>oobabooga</b></td>
|
|
<td align="center" width="130"><b>ComfyUI</b></td>
|
|
<td align="center" width="130"><b>SD WebUI</b></td>
|
|
</tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
## 🔄 How It Works
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
|
|
│ Tool │
|
|
└──────┬──────┘
|
|
│ http://localhost:20128/v1
|
|
↓
|
|
┌──────────────────────────────────────────────────┐
|
|
│ OmniRoute (Smart Router) │
|
|
│ • 🗜️ Prompt Compression (save 15-95% eligible) │
|
|
│ • Format translation (OpenAI ↔ Claude ↔ Gemini) │
|
|
│ • Quota tracking + Embeddings + Images │
|
|
│ • Auto token refresh + Rate limit management │
|
|
└──────┬───────────────────────────────────────────┘
|
|
│
|
|
├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
|
|
│ ↓ quota exhausted
|
|
├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
|
|
│ ↓ budget limit
|
|
├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
|
|
│ ↓ budget limit
|
|
└─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)
|
|
|
|
Result: Never stop coding, minimal cost + 15-95% eligible token savings
|
|
```
|
|
|
|
---
|
|
|
|
## 🗜️ Prompt Compression — Save 15-95% Eligible Tokens Automatically
|
|
|
|
> **Why use many token when few token do trick?** OmniRoute's built-in compression pipeline reduces token usage before requests reach the provider. It combines ideas from [RTK - Rust Token Killer](https://github.com/rtk-ai/rtk) and [Caveman](https://github.com/JuliusBrussee/caveman) (⭐ 51K+).
|
|
|
|
### How It Works
|
|
|
|
Every request passes through the compression pipeline **transparently** — no client changes needed:
|
|
|
|
```
|
|
┌──────────────────┐ ┌─────────────────────────────┐ ┌──────────────┐
|
|
│ Client sends │────▶│ OmniRoute Compression │────▶│ Provider │
|
|
│ full prompt │ │ Pipeline (7 options) │ │ receives │
|
|
│ (10,000 tok) │ │ │ │ compressed │
|
|
│ │ │ 🪶 Lite ........... ~15% │ │ (~1,080 tok)│
|
|
│ │ │ 🪨 Standard ....... ~30% │ │ │
|
|
│ │ │ ⚡ Aggressive ..... ~50% │ │ 💰 up to 95%│
|
|
│ │ │ 🔥 Ultra .......... ~75% │ │ │
|
|
│ │ │ 🧰 RTK ............ 60-90% │ │ │
|
|
│ │ │ 🔗 Stacked ........ 78-95% │ │ │
|
|
└──────────────────┘ └─────────────────────────────┘ └──────────────┘
|
|
```
|
|
|
|
### 7 Compression Options
|
|
|
|
| Mode | Savings | Technique | Best For |
|
|
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |
|
|
| **Off** | 0% | No compression | When you need exact prompts |
|
|
| **🪶 Lite** | ~15% | Whitespace collapse, dedup system prompts, image URL shortening | Always-on safe default |
|
|
| **🪨 Standard (Caveman)** | ~30% | 30+ regex rules: filler removal, context condensation, structural compression, multi-turn dedup | Daily coding with Claude/Codex |
|
|
| **⚡ Aggressive** | ~50% | All standard + progressive message aging + tool result summarization + LLM-based compression | Long sessions with many tool calls |
|
|
| **🔥 Ultra** | ~75% | All aggressive + heuristic token pruning + stopword removal + score-based filtering | Maximum savings when tokens are scarce |
|
|
| **🧰 RTK** | 60-90% | 49 command-aware filters, RTK-style JSON DSL, verify gate, trust-gated custom filters | Shell/test/build/git output in agents |
|
|
| **🔗 Stacked** | 78-95% | RTK first, then Caveman input condensation; ~89% with upstream average math | Mixed prompts with tool logs + prose |
|
|
|
|
### RTK + Caveman Savings Math
|
|
|
|
These numbers are based on the upstream project READMEs under `_references/_outros`:
|
|
|
|
| Source | Upstream claim used by OmniRoute docs |
|
|
| ------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
| Caveman | `~75%` fewer output tokens; benchmark average `65%` output savings, range `22-87%`; `~46%` input compression tool |
|
|
| RTK | `60-90%` command-output token savings; sample session `~118,000 -> ~23,900` tokens, which is `79.7%` saved (`~80%`) |
|
|
|
|
For the default stacked compression combo, OmniRoute runs:
|
|
|
|
```txt
|
|
RTK -> Caveman
|
|
```
|
|
|
|
When both engines can act on the same tool/context payload, the savings compound:
|
|
|
|
```txt
|
|
combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
|
|
average = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
|
|
range = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
|
|
```
|
|
|
|
Caveman output mode is separate from prompt compression. When enabled for responses, use Caveman's
|
|
own upstream output numbers: `65%` average, `~75%` headline, `22-87%` observed range. Total bill
|
|
savings depend on the prompt/output mix, but coding-agent sessions are often tool-context heavy, so
|
|
the `RTK -> Caveman` combo is the best default for maximum context savings.
|
|
|
|
### Before & After (Standard/Caveman Mode)
|
|
|
|
**🗣️ Before compression (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 compression (19 tokens):**
|
|
|
|
> "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."
|
|
|
|
**Same answer. 72% less tokens. Zero accuracy loss.**
|
|
|
|
### Architecture
|
|
|
|
```
|
|
Request Body
|
|
│
|
|
├─ strategySelector.ts ─── Picks mode (config / combo override / auto-trigger)
|
|
│
|
|
├─ lite.ts ─────────────── Whitespace, dedup, image URLs, redundant content
|
|
├─ caveman.ts ──────────── 30+ regex rules via cavemanRules.ts
|
|
│ └─ preservation.ts ─── Protects code blocks, URLs, JSON from compression
|
|
├─ engines/rtk/ ────────── Command detection + JSON DSL filters + raw-output recovery
|
|
├─ engines/registry.ts ─── Shared engine registry for caveman, RTK, and stacked
|
|
├─ aggressive.ts ───────── Summarizer + tool result compressor + progressive aging
|
|
│ ├─ summarizer.ts ───── Rule-based message summarization
|
|
│ ├─ toolResultCompressor.ts ── file/grep/shell/JSON/error compression
|
|
│ └─ progressiveAging.ts ──── Older messages → shorter summaries
|
|
└─ ultra.ts ────────────── Heuristic token scoring + pruning
|
|
└─ ultraHeuristic.ts ─ Stopword detection, score thresholds, force-preserve
|
|
```
|
|
|
|
### Configuration
|
|
|
|
```
|
|
Dashboard → Context & Cache → Caveman / RTK / Compression Combos
|
|
```
|
|
|
|
Or per-combo override:
|
|
|
|
```json
|
|
{
|
|
"comboOverrides": {
|
|
"my-coding-combo": "standard",
|
|
"my-cheap-combo": "ultra"
|
|
}
|
|
}
|
|
```
|
|
|
|
Auto-trigger: set `autoTriggerTokens` to automatically enable compression when a request exceeds a token threshold.
|
|
|
|
Compression combos can also assign a named compression pipeline to routing combos, so a coding combo can use RTK + Caveman while a paid subscription combo stays on lite mode.
|
|
|
|
> 🪨 **Fun fact:** The standard/caveman mode is inspired by [Caveman](https://github.com/JuliusBrussee/caveman) — the viral project that reports 65% average output-token savings while keeping technical accuracy. OmniRoute takes this further with a **7-option pipeline** and a default `RTK -> Caveman` combo that can reach ~89% average savings on eligible tool/context payloads.
|
|
|
|
📖 **Full compression documentation:** [`docs/COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md) • [`docs/RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md) • [`docs/COMPRESSION_ENGINES.md`](docs/COMPRESSION_ENGINES.md) • [`docs/COMPRESSION_RULES_FORMAT.md`](docs/COMPRESSION_RULES_FORMAT.md) • [`docs/COMPRESSION_LANGUAGE_PACKS.md`](docs/COMPRESSION_LANGUAGE_PACKS.md)
|
|
|
|
---
|
|
|
|
## 🎯 What OmniRoute Solves
|
|
|
|
> **Every developer using AI tools faces these problems daily.** OmniRoute solves them all.
|
|
|
|
| # | Problem | OmniRoute Solution |
|
|
| --- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
| 💸 | Subscription quota expires mid-coding | **Smart 4-Tier Fallback** — auto-routes Subscription → API Key → Cheap → Free |
|
|
| 🔌 | Each provider has a different API format | **Format Translation** — unified endpoint translates OpenAI ↔ Claude ↔ Gemini ↔ Responses |
|
|
| 🌐 | AI providers block my country/region | **3-Level Proxy** — global, per-provider, and per-key proxy with TLS fingerprint spoofing |
|
|
| 🆓 | Can't afford AI subscriptions | **11 Free Providers** — Kiro, Qoder, Pollinations, LongCat, Cloudflare AI, NVIDIA NIM... |
|
|
| 🔒 | Gateway is exposed without protection | **API Key Management** — scoping, rotation, IP filtering, rate limiting, prompt injection guard |
|
|
| 🛑 | Provider went down, lost coding flow | **Circuit Breakers** — auto-failover with cooldown, retry, anti-thundering herd |
|
|
| 🔧 | Configuring each CLI tool is tedious | **CLI Tools Dashboard** — one-click setup for Claude Code, Codex, Cursor, OpenClaw, Kilo |
|
|
| 🔑 | Managing OAuth tokens is hell | **Auto Token Refresh** — OAuth PKCE for 8 providers, multi-account, LAN/remote fix |
|
|
| 📊 | Don't know how much I'm spending | **Cost Analytics** — per-token tracking, budget limits, usage stats per API key |
|
|
| 🐛 | Can't diagnose errors in AI calls | **Unified Logs** — 4-tab dashboard (request, proxy, audit, console) + p50/p95/p99 telemetry |
|
|
|
|
<details>
|
|
<summary><b>📖 See all 31 problems OmniRoute solves</b></summary>
|
|
|
|
| # | Problem | Solution |
|
|
| --- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
| 11 | Deploying/maintaining is complex | npm global, Docker multi-arch, Electron, Termux — deploy anywhere |
|
|
| 12 | Interface is English-only | 40+ languages with RTL support |
|
|
| 13 | Need more than chat (images, audio, video) | 10 multi-modal APIs: embeddings, images, video, music, TTS, STT, moderation, rerank, search, batch |
|
|
| 14 | No way to test/compare models | LLM Evals, Translator Playground, Chat Tester, Live Monitor |
|
|
| 15 | Need to scale without losing performance | Semantic cache, request dedup, rate limit detection, queue & pacing |
|
|
| 16 | Want to control model behavior globally | System prompt injection, thinking budget, wildcard routing |
|
|
| 17 | Need MCP tools as first-class features | 29 MCP tools, 3 transports (stdio/SSE/HTTP), 10 scopes, audit trail |
|
|
| 18 | Need A2A orchestration | JSON-RPC 2.0 + SSE streaming, task lifecycle, sync + stream paths |
|
|
| 19 | Need real MCP process health | Runtime heartbeat, PID tracking, UI status cards |
|
|
| 20 | Need auditable MCP execution | SQLite-backed audit with filters, pagination, stats |
|
|
| 21 | Need scoped MCP permissions | 10 granular scopes per integration |
|
|
| 22 | Need operational controls without redeploying | Combo switches, resilience tuning, breaker resets from dashboard |
|
|
| 23 | Need A2A task lifecycle visibility | Task listing/filtering, drill-down, cancellation |
|
|
| 24 | Need active stream metrics | Active stream counters, per-state counts, A2A dashboard cards |
|
|
| 25 | Need standard agent discovery | Agent Card at `/.well-known/agent.json` |
|
|
| 26 | Need protocol discoverability | Consolidated Endpoints page with Proxy, MCP, A2A, API tabs |
|
|
| 27 | Need E2E protocol validation | Real MCP SDK + A2A client flows in `test:protocols:e2e` |
|
|
| 28 | Need unified observability | Health + audit + telemetry across OpenAI, MCP, and A2A layers |
|
|
| 29 | Need one runtime for proxy + tools + agents | OpenAI proxy + MCP + A2A in one stack with shared auth/resilience |
|
|
| 30 | Need agentic workflows without glue-code | Unified endpoint, protocol UIs, production-ready foundations |
|
|
| 31 | Long sessions crash with context limits | Proactive context compression, structural integrity guards, multi-layer dropping |
|
|
|
|
</details>
|
|
|
|
📖 **Deep dives:** [Resilience Guide](docs/RESILIENCE_GUIDE.md) • [Proxy Guide](docs/PROXY_GUIDE.md) • [Setup Guide](docs/SETUP_GUIDE.md) • [Compression Guide](docs/COMPRESSION_GUIDE.md)
|
|
|
|
---
|
|
|
|
## 🆓 Start Free — Zero Configuration Cost
|
|
|
|
> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.
|
|
|
|
| Step | Action | Providers Unlocked |
|
|
| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |
|
|
| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 — **unlimited** |
|
|
| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **unlimited** |
|
|
| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... — **unlimited** |
|
|
| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mo free** |
|
|
| 5 | `/dashboard/combos` → **Free Stack ($0)** template | Round-robin all free providers automatically |
|
|
|
|
**Point any IDE/CLI to:** `http://localhost:20128/v1` · API Key: `any-string` · Done.
|
|
|
|
> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).
|
|
|
|
## ⚡ Quick Start
|
|
|
|
### 1) Install and run
|
|
|
|
```bash
|
|
npm install -g omniroute
|
|
omniroute
|
|
```
|
|
|
|
Dashboard opens at `http://localhost:20128` · API at `http://localhost:20128/v1`.
|
|
|
|
### 2) Connect providers
|
|
|
|
1. Dashboard → **Providers** → connect at least one provider (OAuth or API key)
|
|
2. Dashboard → **Endpoints** → create an API key
|
|
3. Dashboard → **Combos** → set your fallback chain (optional)
|
|
|
|
### 3) Point your coding tool
|
|
|
|
```txt
|
|
Base URL: http://localhost:20128/v1
|
|
API Key: [copy from Endpoint page]
|
|
Model: if/kimi-k2-thinking (or any provider/model)
|
|
```
|
|
|
|
Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and any OpenAI-compatible tool.
|
|
|
|
<details>
|
|
<summary><b>📦 More install methods (Docker, source, Arch, Void, pnpm)</b></summary>
|
|
|
|
**Docker:**
|
|
|
|
```bash
|
|
docker run -d --name omniroute --restart unless-stopped -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
|
|
```
|
|
|
|
**From source:**
|
|
|
|
```bash
|
|
cp .env.example .env && npm install
|
|
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
|
|
```
|
|
|
|
**pnpm:** `pnpm install -g omniroute && pnpm approve-builds -g && omniroute`
|
|
|
|
**Arch Linux (AUR):** `yay -S omniroute-bin && systemctl --user enable --now omniroute.service`
|
|
|
|
**MCP:** `omniroute --mcp` (stdio transport)
|
|
|
|
**CLI options:** `omniroute --port 3000`, `omniroute --no-open`, `omniroute --help`
|
|
|
|
**Split-port mode:** `PORT=20128 DASHBOARD_PORT=20129 omniroute`
|
|
|
|
**Uninstall:** `npm run uninstall` (keeps data) or `npm run uninstall:full` (removes everything)
|
|
|
|
📖 Full details: [Setup Guide](#-setup-guide) · [Docker](#-docker) · [Void Linux template](#-quick-start)
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 🐳 Docker
|
|
|
|
OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
|
|
|
|
**Quick run:**
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name omniroute \
|
|
--restart unless-stopped \
|
|
--stop-timeout 40 \
|
|
-p 20128:20128 \
|
|
-v omniroute-data:/app/data \
|
|
diegosouzapw/omniroute:latest
|
|
```
|
|
|
|
**With environment file:**
|
|
|
|
```bash
|
|
# Copy and edit .env first
|
|
cp .env.example .env
|
|
|
|
docker run -d \
|
|
--name omniroute \
|
|
--restart unless-stopped \
|
|
--stop-timeout 40 \
|
|
--env-file .env \
|
|
-p 20128:20128 \
|
|
-v omniroute-data:/app/data \
|
|
diegosouzapw/omniroute:latest
|
|
```
|
|
|
|
**Using Docker Compose:**
|
|
|
|
```bash
|
|
# Base profile (no CLI tools)
|
|
docker compose --profile base up -d
|
|
|
|
# CLI profile (Claude Code, Codex, OpenClaw built-in)
|
|
docker compose --profile cli up -d
|
|
```
|
|
|
|
Dashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard → Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL. Endpoint tunnel panels, including Cloudflare, Tailscale, and ngrok, can be shown or hidden from `Settings → Appearance` without changing active tunnel state.
|
|
|
|
Notes:
|
|
|
|
- Quick Tunnel URLs are temporary and change after every restart.
|
|
- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.
|
|
- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
|
|
- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.
|
|
- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.
|
|
- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.
|
|
- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.
|
|
- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.
|
|
|
|
**Using Docker Compose with Caddy (HTTPS Auto-TLS):**
|
|
|
|
OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.
|
|
|
|
```yaml
|
|
services:
|
|
omniroute:
|
|
image: diegosouzapw/omniroute:latest
|
|
container_name: omniroute
|
|
restart: unless-stopped
|
|
volumes:
|
|
- omniroute-data:/app/data
|
|
environment:
|
|
- PORT=20128
|
|
- NEXT_PUBLIC_BASE_URL=https://your-domain.com
|
|
|
|
caddy:
|
|
image: caddy:latest
|
|
container_name: caddy
|
|
restart: unless-stopped
|
|
ports:
|
|
- "80:80"
|
|
- "443:443"
|
|
command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128
|
|
|
|
volumes:
|
|
omniroute-data:
|
|
```
|
|
|
|
| Image | Tag | Size | Description |
|
|
| ------------------------ | -------- | ------ | --------------------- |
|
|
| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
|
|
| `diegosouzapw/omniroute` | `3.7.8` | ~250MB | Current version |
|
|
|
|
📖 **Full Docker documentation:** [`docs/DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md) — Compose profiles, Caddy HTTPS, Cloudflare tunnels, and more.
|
|
|
|
---
|
|
|
|
## 📱 Multi-Platform — Run Anywhere
|
|
|
|
> OmniRoute runs on **Web**, **Desktop (Electron)**, **Android (Termux)**, and as a **Progressive Web App (PWA)**.
|
|
|
|
| Platform | Install | Highlights |
|
|
| -------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
|
|
| 🖥️ **Desktop** | `npm run electron:build` | Native window, system tray, auto-start, offline mode — Windows/macOS/Linux |
|
|
| 📱 **Android** | `pkg install nodejs-lts && npx -y omniroute` | ARM native, no root, 24/7 via Termux:Boot — your phone is an AI server |
|
|
| 📲 **PWA** | "Add to Home Screen" in browser | Fullscreen, offline page, service worker caching — Android/iOS/Desktop |
|
|
|
|
<details>
|
|
<summary><b>🖥️ Desktop App details</b></summary>
|
|
|
|
- Native Electron app with system tray, auto-start, native notifications
|
|
- One-click install: NSIS (Windows), DMG (macOS), AppImage (Linux)
|
|
- Dev: `npm run electron:dev` · Build: `npm run electron:build`
|
|
- 📖 Full docs: [`electron/README.md`](electron/README.md)
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>📱 Android (Termux) details</b></summary>
|
|
|
|
```bash
|
|
pkg update && pkg install nodejs-lts python build-essential git
|
|
npx -y omniroute@latest
|
|
```
|
|
|
|
Access from any device on the same network: `http://PHONE_IP:20128/v1`
|
|
|
|
- 📖 Full guide: [`docs/TERMUX_GUIDE.md`](docs/TERMUX_GUIDE.md)
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>📲 PWA details</b></summary>
|
|
|
|
- **Android (Chrome):** ⋮ → "Add to Home screen"
|
|
- **iOS (Safari):** Share → "Add to Home Screen"
|
|
- **Desktop (Chrome/Edge):** Install icon in address bar
|
|
- 📖 Full docs: [`docs/PWA_GUIDE.md`](docs/PWA_GUIDE.md)
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 🌍 Bypass Geographic Blocks — Use AI From Any Country
|
|
|
|
> 🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 **In Russia, China, Iran, or any blocked region?** OmniRoute's 3-level proxy system solves this completely.
|
|
|
|
| Level | Badge | Configure In | Use Case |
|
|
| ------------------ | ----- | ------------------ | ------------------------------- |
|
|
| **Global** | 🟢 | Settings → Proxy | All traffic through one proxy |
|
|
| **Per-Provider** | 🟡 | Provider → Proxy | Only specific providers proxied |
|
|
| **Per-Connection** | 🔵 | Connection → Proxy | Each API key uses its own proxy |
|
|
|
|
**What gets proxied:** API requests ✅ • OAuth flows ✅ • Connection tests ✅ • Token refresh ✅ • Model sync ✅
|
|
|
|
**Protocols:** HTTP/HTTPS, SOCKS5 (`ENABLE_SOCKS5_PROXY=true`), Authenticated proxies
|
|
|
|
### 🆓 1proxy — Free Proxy Marketplace
|
|
|
|
> Contributed by [@oyi77](https://github.com/oyi77) — [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847)
|
|
|
|
No proxy? Use the built-in **1proxy** integration for **hundreds of free, validated proxies** worldwide:
|
|
|
|
- One-click sync (up to 500 proxies) • Quality scores (0-100) • Country filter • Auto-rotation (quality/random/sequential) • Auto-degradation • Circuit breaker
|
|
|
|
### Anti-Detection
|
|
|
|
- 🔒 **TLS Fingerprint Spoofing** — browser-like TLS via `wreq-js`
|
|
- 🔏 **CLI Fingerprint Matching** — matches native CLI binary signatures
|
|
- 🏠 **Proxy IP Preservation** — stealth + IP masking simultaneously
|
|
|
|
📖 **Full proxy documentation:** [`docs/PROXY_GUIDE.md`](docs/PROXY_GUIDE.md)
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## 💰 Pricing at a Glance
|
|
|
|
| Tier | Provider | Cost | Quota Reset | Best For |
|
|
| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |
|
|
| **💳 SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |
|
|
| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |
|
|
| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
|
|
| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |
|
|
| **🔑 API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |
|
|
| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |
|
|
| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |
|
|
| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |
|
|
| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** 🆕 | None | Fastest + tool calling, ultralow |
|
|
| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M 🆕 | None | Reasoning flagship from xAI |
|
|
| | Mistral | Free trial + paid | Rate limited | European AI |
|
|
| | OpenRouter | Pay-per-use | None | 100+ models aggr. |
|
|
| | AgentRouter 🆕 | Pay-per-use | None | $200 free credits at signup |
|
|
| **💰 CHEAP** | GLM-5 (via Z.AI) 🆕 | $0.5/1M | Daily 10AM | 128K output, newest flagship |
|
|
| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
|
|
| | MiniMax M2.5 🆕 | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |
|
|
| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
|
|
| | Kimi K2.5 (Moonshot API) 🆕 | Pay-per-use | None | Direct Moonshot API access |
|
|
| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
|
|
| **🆓 FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |
|
|
| | Qwen | **$0** | Unlimited | 4 models unlimited |
|
|
| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |
|
|
| | LongCat Flash-Lite 🆕 | **$0** (50M tok/day 🔥) | 1 RPS | Largest free quota on Earth |
|
|
| | Pollinations AI 🆕 | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |
|
|
| | Cloudflare Workers AI 🆕 | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |
|
|
| | Scaleway AI 🆕 | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |
|
|
|
|
> 🆕 **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms — 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.
|
|
|
|
**💡 See the full [$0 Free Stack (11 providers)](#-free-models--11-providers-0-forever) below.**
|
|
|
|
> 💡 **Understanding Dashboard Costs:**
|
|
>
|
|
> The "cost" displayed in the Usage Analytics page is **for tracking and comparison purposes only**.
|
|
> OmniRoute itself **never charges you anything** — it's free, open-source software running on your machine.
|
|
> If your dashboard shows "$290 total cost" while using free models, that's how much you **saved** compared to paid API pricing.
|
|
> Think of it as a **savings tracker**, not a bill.
|
|
|
|
---
|
|
|
|
## 🆓 Free Models — 11 Providers, $0 Forever
|
|
|
|
> Combine all free providers into one unbreakable combo — OmniRoute auto-routes between them when quota runs out.
|
|
|
|
| Provider | Prefix | Free Models | Quota |
|
|
| ----------------- | ----------- | ------------------------------------------------------------- | -------------------- |
|
|
| **Kiro** | `kr/` | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | 50 CREDITS per month |
|
|
| **Qoder** | `if/` | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2.1 | ♾️ Unlimited |
|
|
| **Qwen** | `qw/` | qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next | ♾️ Unlimited |
|
|
| **Pollinations** | `pol/` | GPT-5, Claude, Gemini, DeepSeek, Llama 4, Mistral | No key needed |
|
|
| **LongCat** | `lc/` | LongCat-Flash-Lite | 50M tokens/day 🔥 |
|
|
| **Gemini CLI** | `gc/` | gemini-3-flash, gemini-2.5-pro | 180K tok/mo |
|
|
| **Cloudflare AI** | `cf/` | 50+ models (Llama, Gemma, Mistral, Whisper) | 10K Neurons/day |
|
|
| **Groq** | `groq/` | Llama 3.3 70B, Qwen3 32B, Kimi K2 | 14.4K RPD |
|
|
| **NVIDIA NIM** | `nvidia/` | 129 models (DeepSeek, Llama, GLM, Kimi) | ~40 RPM |
|
|
| **Cerebras** | `cerebras/` | Qwen3 235B, GPT-OSS 120B, Llama 3.1 | 1M tok/day |
|
|
| **Scaleway** | `scw/` | Qwen3 235B, Llama 70B, DeepSeek V3 | 1M tokens (EU) |
|
|
|
|
<details>
|
|
<summary><b>📖 25+ more free providers — Groq, Cerebras, Mistral, GitHub Models, OpenRouter, and more</b></summary>
|
|
|
|
**Also free (API Key required):**
|
|
Mistral (1B tok/month) · OpenRouter (35+ `:free` models) · GitHub Models (GPT-5, 45+ models) ·
|
|
Cohere (1K calls/month) · Z.AI/GLM (permanent free Flash models) · SiliconFlow (1K RPM, 50K TPM) ·
|
|
Kilo Code (~200 req/hr auto-router) · HuggingFace ($0.10/mo credits) · Ollama Cloud (400+ models) ·
|
|
LLM7.io (30+ models) · Kluster AI · IBM watsonx (300K tok/month) · OpenCode Zen · Vercel AI Gateway ($5/mo)
|
|
|
|
**Trial credits (one-time):**
|
|
Baseten ($30) · NLP Cloud ($15) · AI21 ($10) · Upstage ($10) · SambaNova ($5) · Modal ($5/mo) ·
|
|
Fireworks ($1) · Nebius ($1) · Inference.net ($1 + $25 survey) · Hyperbolic ($1) · Novita ($0.50)
|
|
|
|
**China-based (free tiers):**
|
|
ModelScope · Tencent Hunyuan · Volcengine · ChatAnywhere · InternAI · Bigmodel
|
|
|
|
**Combined capacity: ~31,000+ RPD · ~32B+ tokens/month · 500+ models · $0**
|
|
|
|
</details>
|
|
|
|
📖 **Complete free provider directory:** [`docs/FREE_TIERS.md`](docs/FREE_TIERS.md) — 25+ providers, quotas, base URLs, model tables, and OmniRoute combo setup.
|
|
|
|
---
|
|
|
|
## 🎙️ Free Transcription Combo
|
|
|
|
> Transcribe any audio/video for **$0** — Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.
|
|
|
|
| Provider | Free Credits | Best Model | Rate Limit |
|
|
| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |
|
|
| 🟢 **Deepgram** | **$200 free** (signup) | `nova-3` — best accuracy, 30+ languages | No RPM limit on free credits |
|
|
| 🔵 **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` — chapters, sentiment, PII | No RPM limit on free credits |
|
|
| 🔴 **Groq** | **Free forever** | `whisper-large-v3` — OpenAI Whisper | 30 RPM (rate limited) |
|
|
|
|
---
|
|
|
|
**Suggested combo in `/dashboard/combos`:**
|
|
|
|
```
|
|
Name: free-transcription
|
|
Strategy: Priority
|
|
Nodes:
|
|
[1] deepgram/nova-3 → uses $200 free first
|
|
[2] assemblyai/universal-3-pro → fallback when Deepgram credits run out
|
|
[3] groq/whisper-large-v3 → free forever, emergency fallback
|
|
```
|
|
|
|
Then in `/dashboard/media` → **Transcription** tab: upload any audio or video file → select your combo endpoint → get transcription in supported formats.
|
|
|
|
## 💡 Key Features
|
|
|
|
> **4,690+ automated tests** across 517 test files. Not just a relay — a full operational platform.
|
|
|
|
| Feature | Why It Matters |
|
|
| ---------------------------------------------------------------------------------------------------- | -------------------------------- |
|
|
| 🧠 **Smart 4-Tier Fallback** — Subscription → API → Cheap → Free | Never stop coding, zero downtime |
|
|
| 🔄 **Format Translation** — OpenAI ↔ Claude ↔ Gemini ↔ Responses API | Works with ANY CLI tool |
|
|
| 🗜️ **Prompt Compression** — 7 options including Caveman, RTK, and stacked pipelines | Save 15-95% eligible tokens |
|
|
| 🤖 **MCP Server** — 37 tools, 3 transports (stdio/SSE/HTTP), 10 scopes | IDE/agent tool integration |
|
|
| 🛡️ **Resilience Engine** — circuit breakers, cooldowns, TLS spoofing, anti-thundering herd | Auto-recovery from any failure |
|
|
| 🎵 **10 Multi-Modal APIs** — chat, embed, images, video, music, TTS, STT, moderation, rerank, search | One endpoint for everything |
|
|
| 🌍 **3-Level Proxy** — global, per-provider, per-key + 1proxy free marketplace | Access AI from any country |
|
|
| 📊 **Full Observability** — unified logs, p50/p95/p99 telemetry, cost tracking, budget controls | Know exactly what's happening |
|
|
|
|
<details>
|
|
<summary><b>📋 Complete feature list — 30+ capabilities</b></summary>
|
|
|
|
**Routing & Intelligence**
|
|
|
|
- 13 balancing strategies (priority, weighted, round-robin, P2C, cost-optimized, context-relay...)
|
|
- Task-aware smart routing (coding/vision/analysis) · Context relay session handoffs
|
|
- Thinking budget controls (passthrough/auto/custom) · Wildcard routing · System prompt injection
|
|
|
|
**Translation & Compatibility**
|
|
|
|
- Auto token refresh (OAuth PKCE for 8 providers) · Multi-account round-robin
|
|
- Responses API — full `/v1/responses` for Codex · Batch API with Files API
|
|
- OpenAPI 3.0 live spec + Try-It UI
|
|
|
|
**Protocols**
|
|
|
|
- A2A Server — JSON-RPC 2.0, SSE streaming, task lifecycle, skills
|
|
- ACP — CLI agent discovery (14 agents + custom)
|
|
|
|
**Platform**
|
|
|
|
- Desktop (Electron) · Android (Termux) · PWA · Docker (AMD64 + ARM64)
|
|
- Cloudflare / Tailscale / ngrok tunnels · 40+ languages with RTL
|
|
- Semantic + signature cache (two-tier) · Request idempotency + deduplication
|
|
|
|
**Observability**
|
|
|
|
- Health dashboard — uptime, breakers, cache, lockouts
|
|
- Evaluation framework — golden set testing · Webhooks · Compliance audit
|
|
|
|
**v3.6+ Highlights:**
|
|
V1 WebSocket Bridge · Sync Tokens & Config Bundle · GLM Thinking (glmt) · Hybrid Token Counting ·
|
|
Safe Outbound Fetch · Wait For Cooldown · Runtime Env Validation · Vision Bridge ·
|
|
Grok-4 Fast · GLM-5 via Z.AI · MiniMax M2.5 · toolCalling flag ·
|
|
Multilingual Intent Detection · Benchmark-Driven Fallbacks · Request Deduplication
|
|
|
|
**Architecture Examples:**
|
|
|
|
```txt
|
|
Combo: "my-coding-stack" Format Translation:
|
|
1. cc/claude-opus-4-7 CLI → OpenAI format
|
|
2. nvidia/llama-3.3-70b OmniRoute → translates
|
|
3. glm/glm-4.7 Provider → native format
|
|
4. if/kimi-k2-thinking
|
|
```
|
|
|
|
📖 [MCP Server README](open-sse/mcp-server/README.md) · [A2A Server README](src/lib/a2a/README.md) · [Resilience Guide](docs/RESILIENCE_GUIDE.md) · [Features Gallery](docs/FEATURES.md)
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 🎯 Use Cases — Ready-Made Combo Playbooks
|
|
|
|
### Case 1: "I have a Claude Pro subscription"
|
|
|
|
**Problem:** Quota expires unused, rate limits during heavy coding sessions.
|
|
|
|
```
|
|
Combo: "maximize-claude"
|
|
1. cc/claude-opus-4-7 (use subscription fully)
|
|
2. glm/glm-5.1 (cheap backup when quota out — $0.5/1M)
|
|
3. kr/claude-sonnet-4.5 (free emergency fallback via Kiro)
|
|
|
|
Compression: standard (caveman) — saves 30% tokens = stretch quota further
|
|
Monthly cost: $20 (subscription) + ~$3 (backup) = $23 total
|
|
vs. $20 + hitting limits + lost productivity = frustration
|
|
```
|
|
|
|
### Case 2: "I want $0 forever"
|
|
|
|
**Problem:** Can't afford subscriptions, need reliable AI for coding.
|
|
|
|
```
|
|
Combo: "free-forever"
|
|
1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited via Kiro)
|
|
2. if/kimi-k2-thinking (reasoning model free via Qoder)
|
|
3. pol/gpt-5 (GPT-5 free via Pollinations — no key)
|
|
4. lc/longcat-flash-lite (50M tokens/day free backup)
|
|
|
|
Compression: aggressive — saves 50% tokens = double your free quota
|
|
Monthly cost: $0
|
|
Quality: Production-ready models + 50% token savings
|
|
```
|
|
|
|
### Case 3: "I need 24/7 coding, no interruptions"
|
|
|
|
**Problem:** Deadlines, can't afford any downtime.
|
|
|
|
```
|
|
Combo: "always-on"
|
|
1. cc/claude-opus-4-7 (best quality — subscription)
|
|
2. cx/gpt-5.5 (second subscription — OpenAI)
|
|
3. glm/glm-5.1 (cheap, resets daily — $0.5/1M)
|
|
4. minimax/MiniMax-M2.5 (cheapest paid — $0.3/1M)
|
|
5. kr/claude-sonnet-4.5 (free unlimited — never fails)
|
|
|
|
Compression: lite — saves 15% tokens passively, zero risk
|
|
Result: 5 layers of fallback = zero downtime
|
|
Monthly cost: $20-200 (subscriptions) + $5-10 (backup)
|
|
```
|
|
|
|
### Case 4: "I'm in a blocked region (Russia, China, Iran...)"
|
|
|
|
**Problem:** AI providers block my country, VPNs are slow.
|
|
|
|
```
|
|
Combo: "unblocked-ai"
|
|
1. kr/claude-sonnet-4.5 (free via Kiro + proxy)
|
|
2. pol/deepseek-r1 (Pollinations — no geo-block)
|
|
3. groq/llama-3.3-70b (Groq + proxy)
|
|
|
|
Proxy: Global proxy set in Settings → or per-provider proxy override
|
|
Result: Access ALL providers from ANY country
|
|
Monthly cost: $0 (free providers) + $0 (1proxy free marketplace)
|
|
```
|
|
|
|
### Case 5: "I want maximum token savings"
|
|
|
|
**Problem:** Token costs are eating my budget, need to squeeze every token.
|
|
|
|
```
|
|
Combo: "ultra-saver"
|
|
1. cc/claude-opus-4-7 (subscription — best quality)
|
|
2. glm/glm-5.1 (cheap backup)
|
|
|
|
Compression: ultra — saves 75% tokens
|
|
Result: 10K token prompt → 2.5K tokens sent
|
|
Montly savings: ~$150-300/month in token costs for heavy users
|
|
```
|
|
|
|
## 🧪 Evaluations (Evals)
|
|
|
|
OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics → Evals** in the dashboard.
|
|
|
|
### Built-in Golden Set
|
|
|
|
The pre-loaded "OmniRoute Golden Set" contains test cases for:
|
|
|
|
- Greetings, math, geography, code generation
|
|
- JSON format compliance, translation, markdown generation
|
|
- Safety refusal (harmful content), counting, boolean logic
|
|
|
|
### Evaluation Strategies
|
|
|
|
| Strategy | Description | Example |
|
|
| ---------- | ------------------------------------------------ | -------------------------------- |
|
|
| `exact` | Output must match exactly | `"4"` |
|
|
| `contains` | Output must contain substring (case-insensitive) | `"Paris"` |
|
|
| `regex` | Output must match regex pattern | `"1.*2.*3"` |
|
|
| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |
|
|
|
|
---
|
|
|
|
## 📖 Setup Guide
|
|
|
|
### Connect Your Coding Tool
|
|
|
|
Point any OpenAI-compatible tool to OmniRoute:
|
|
|
|
```txt
|
|
Base URL: http://localhost:20128/v1
|
|
API Key: [from Dashboard → Endpoints]
|
|
```
|
|
|
|
| Tool | Config Location |
|
|
| --------------- | ----------------------------------------------------------------------------------------- |
|
|
| **Claude Code** | `claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream` |
|
|
| **Codex CLI** | `OPENAI_BASE_URL=http://localhost:20128/v1 OPENAI_API_KEY=your-key codex` |
|
|
| **Cursor** | Settings → Models → Add Model → Override Base URL |
|
|
| **Cline** | Extension settings → Custom API Base URL |
|
|
| **OpenClaw** | `OPENAI_BASE_URL=http://localhost:20128/v1 openclaw` |
|
|
| **Gemini CLI** | Uses native OAuth via OmniRoute — connect in Providers |
|
|
|
|
### Protocols (MCP + A2A)
|
|
|
|
```bash
|
|
# MCP (stdio transport)
|
|
omniroute --mcp
|
|
|
|
# A2A (JSON-RPC 2.0)
|
|
curl http://localhost:20128/.well-known/agent.json
|
|
```
|
|
|
|
### Key Environment Variables
|
|
|
|
| Variable | Default | Purpose |
|
|
| -------------------- | -------------- | ----------------------------------------- |
|
|
| `PORT` | `20128` | API and dashboard port |
|
|
| `DASHBOARD_PORT` | — | Separate dashboard port (split-port mode) |
|
|
| `REQUIRE_API_KEY` | `false` | Require API key for all requests |
|
|
| `DATA_DIR` | `~/.omniroute` | Database and config storage |
|
|
| `REQUEST_TIMEOUT_MS` | `600000` | Upstream response timeout |
|
|
|
|
<details>
|
|
<summary><b>📖 Full Setup Guide — All CLI tools, protocols, and environment variables</b></summary>
|
|
|
|
📖 **Complete documentation:**
|
|
|
|
- [User Guide](docs/USER_GUIDE.md) — Providers, combos, CLI integration
|
|
- [API Reference](docs/API_REFERENCE.md) — All endpoints with examples
|
|
- [MCP Server](open-sse/mcp-server/README.md) — 37 tools, IDE configs
|
|
- [A2A Server](src/lib/a2a/README.md) — JSON-RPC, skills, streaming
|
|
- [Environment Config](docs/ENVIRONMENT.md) — Complete `.env` reference
|
|
- [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) — VM + nginx + Cloudflare
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## ❓ Frequently Asked Questions
|
|
|
|
<details>
|
|
<summary><b>📊 Why does my dashboard show high costs if I'm using free models?</b></summary>
|
|
|
|
The dashboard tracks your token usage and displays **estimated costs** as if you were using paid APIs directly. This is **not actual billing** — it's a reference to show how much you're saving.
|
|
|
|
**Example:**
|
|
|
|
- **Dashboard shows:** "$290 total cost"
|
|
- **Reality:** You're using Kiro + Qoder (FREE unlimited)
|
|
- **Your actual cost:** **$0.00**
|
|
- **What $290 means:** Amount you **saved** by using free models instead of paid APIs!
|
|
|
|
The cost display is a "savings tracker" to help you understand your usage patterns and optimization opportunities.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>💳 Will I be charged by OmniRoute?</b></summary>
|
|
|
|
**No.** OmniRoute is free, open-source software that runs on your own computer. It never charges you anything.
|
|
|
|
**You only pay:**
|
|
|
|
- ✅ **Subscription providers** (Claude Code $20/mo, Codex $20-200/mo) → Pay them directly on their websites
|
|
- ✅ **API key providers** (DeepSeek, xAI, etc.) → Pay them directly, OmniRoute just routes your requests
|
|
- ❌ **OmniRoute itself** → **Never charges anything, ever**
|
|
|
|
OmniRoute is a local proxy/router. It doesn't have your credit card, can't send invoices, and has no billing system. It's completely free software.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>🆓 Are FREE providers really unlimited?</b></summary>
|
|
|
|
**Yes!** The current FREE providers are genuinely free with **no hidden charges**:
|
|
|
|
- **Kiro AI**: Free unlimited Claude Sonnet/Haiku via AWS Builder ID / Google / GitHub OAuth
|
|
- **Qoder**: Free unlimited kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 via PAT token
|
|
- **Pollinations AI**: No API key needed — GPT-5, Claude, DeepSeek, Llama 4
|
|
- **LongCat Flash-Lite**: 50M tokens/day — largest free quota available
|
|
- **Cloudflare Workers AI**: 10K Neurons/day — 50+ models at the edge
|
|
|
|
OmniRoute just routes your requests to them — there's no "catch" or future billing.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>💰 How do I minimize my actual AI costs?</b></summary>
|
|
|
|
**Free-First Strategy:**
|
|
|
|
1. **Start with 100% free combo:**
|
|
|
|
```
|
|
1. kr/claude-sonnet-4.5 (Kiro — unlimited free)
|
|
2. if/kimi-k2-thinking (Qoder — unlimited free)
|
|
3. pol/gpt-5 (Pollinations — no key needed)
|
|
```
|
|
|
|
**Cost: $0/month**
|
|
|
|
2. **Enable Prompt Compression** — even `lite` mode saves ~15% passively
|
|
|
|
3. **Add cheap backup** only if you need it:
|
|
|
|
```
|
|
4. glm/glm-5.1 ($0.5/1M tokens)
|
|
```
|
|
|
|
**Additional cost: Only pay for what you actually use**
|
|
|
|
4. **Use subscription providers last** — only if you already have them. OmniRoute helps maximize their value through quota tracking.
|
|
|
|
**Result:** Most users can operate at **$0/month** using only free tiers!
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>🗜️ Will compression affect response quality?</b></summary>
|
|
|
|
**No.** Compression only affects the **input** (your prompt), not the model's response. Each mode has been designed to preserve technical accuracy:
|
|
|
|
- **Lite** (~15%): Only whitespace/formatting — zero semantic change
|
|
- **Standard** (~30%): Removes filler words ("please", "I think", "basically") — same meaning
|
|
- **Aggressive** (~50%): Summarizes old messages + compresses tool outputs — core context preserved
|
|
- **Ultra** (~75%): Heuristic pruning — use only when token budget is critical
|
|
|
|
Code blocks, URLs, JSON, and structured data are **always protected** from compression via the preservation engine.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>🌍 Does OmniRoute work in countries where AI is blocked?</b></summary>
|
|
|
|
**Yes!** OmniRoute has a 3-level proxy system:
|
|
|
|
1. **Global proxy** — all requests go through your proxy
|
|
2. **Per-provider proxy** — different proxy per provider
|
|
3. **Per-API-key proxy** — different proxy per key
|
|
|
|
Plus the **1proxy free marketplace** for community-shared proxies. Users in Russia, China, Iran, and other restricted regions can access all 160+ providers through OmniRoute's proxy infrastructure.
|
|
|
|
See the [Proxy Guide](docs/PROXY_GUIDE.md) for setup instructions.
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
| Problem | Quick Fix |
|
|
| --------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
| **"Language model did not provide messages"** | Provider quota exhausted → check quota tracker, use combo fallback |
|
|
| **Rate limiting (429)** | Add fallback combo: `cc/claude → glm/glm-4.7 → if/kimi-k2-thinking` |
|
|
| **OAuth token expired** | Auto-refreshed by OmniRoute. If stuck: delete + re-auth in Providers |
|
|
| **`unsupported_country_region_territory`** | Configure proxy in Settings → Proxy (see [Proxy Guide](docs/PROXY_GUIDE.md)) |
|
|
| **Docker SQLite locks** | Use `--stop-timeout 40` for clean WAL checkpoint on shutdown |
|
|
| **Node.js runtime errors** | Use Node.js `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25` (24 LTS recommended) |
|
|
| **`system-info` for bug reports** | Run `npm run system-info` and attach `system-info.txt` to your issue |
|
|
|
|
📖 **Full troubleshooting guide:** [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md)
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
<details>
|
|
<summary><b>Click to expand tech stack details</b></summary>
|
|
|
|
- **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
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 📖 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.**
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="160">
|
|
<a href="https://github.com/oyi77">
|
|
<img src="https://github.com/oyi77.png" width="80" style="border-radius:50%" alt="oyi77"/><br/>
|
|
<b>oyi77</b>
|
|
</a><br/>
|
|
<sub>🥇 190 commits • +72K lines</sub><br/>
|
|
<sub>Analytics engine, SQL aggregations,<br/>proxy marketplace, test coverage</sub>
|
|
</td>
|
|
<td align="center" width="160">
|
|
<a href="https://github.com/christopher-s">
|
|
<img src="https://github.com/christopher-s.png" width="80" style="border-radius:50%" alt="Chris Staley"/><br/>
|
|
<b>Chris Staley</b>
|
|
</a><br/>
|
|
<sub>🥈 72 commits • +5.7K lines</sub><br/>
|
|
<sub>SSE stream hardening, Responses API,<br/>Gemini pagination, test regression fixes</sub>
|
|
</td>
|
|
<td align="center" width="160">
|
|
<a href="https://github.com/zenobit">
|
|
<img src="https://github.com/zenobit.png" width="80" style="border-radius:50%" alt="zenobit"/><br/>
|
|
<b>zenobit</b>
|
|
</a><br/>
|
|
<sub>🥉 62 commits • +24K lines</sub><br/>
|
|
<sub>CI/CD pipeline, i18n for 33 languages,<br/>Void Linux package, platform fixes</sub>
|
|
</td>
|
|
<td align="center" width="160">
|
|
<a href="https://github.com/rdself">
|
|
<img src="https://github.com/rdself.png" width="80" style="border-radius:50%" alt="R.D. & Randi"/><br/>
|
|
<b>R.D. & Randi</b>
|
|
</a><br/>
|
|
<sub>🏅 107 commits • +28K lines</sub><br/>
|
|
<sub>Endpoints page, tunnel integrations,<br/>Docker workflows, A2A status, compression UI</sub>
|
|
</td>
|
|
<td align="center" width="160">
|
|
<a href="https://github.com/benzntech">
|
|
<img src="https://github.com/benzntech.png" width="80" style="border-radius:50%" alt="benzntech"/><br/>
|
|
<b>benzntech</b>
|
|
</a><br/>
|
|
<sub>🏅 20 commits • +7.5K lines</sub><br/>
|
|
<sub>Electron desktop app, auto-updater,<br/>release build workflows, cross-platform CI</sub>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
> 🙏 These contributors' features, bug fixes, and infrastructure improvements are a **core part** of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.
|
|
|
|
---
|
|
|
|
## 👥 Contributors
|
|
|
|
[](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 v2.0.0 --title "v2.0.0" --generate-notes
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Star History
|
|
|
|
<a href="https://www.star-history.com/?repos=diegosouzapw%2Fomniroute&type=date&legend=top-left">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&theme=dark&legend=top-left" />
|
|
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
|
|
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=diegosouzapw/omniroute&type=date&legend=top-left" />
|
|
</picture>
|
|
</a>
|
|
|
|
## 🌍 StarMapper
|
|
|
|
<a href="https://starmapper.bruniaux.com/diegosouzapw/omniroute">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=dark" />
|
|
<source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute?theme=light" />
|
|
<img alt="StarMapper" src="https://starmapper.bruniaux.com/api/map-image/diegosouzapw/omniroute" />
|
|
</picture>
|
|
</a>
|
|
|
|
## 🙏 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.
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
<sub>Built with ❤️ for developers who code 24/7</sub>
|
|
<br/>
|
|
<sub><a href="https://omniroute.online">omniroute.online</a></sub>
|
|
</div>
|
|
<!-- GitHub Discussions enabled for community Q&A -->
|