OmniRoute Dashboard # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. _Your universal API proxy โ€” one endpoint, 36+ providers, zero downtime._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Audio โ€ข Reranking โ€ข 100% TypeScript** --- [![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute) [![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute) [![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE) [![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) [![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) [๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) ๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](README.pt-BR.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](README.es.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](README.fr.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](README.it.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](README.ru.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](README.zh-CN.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](README.de.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](README.in.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](README.th.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](README.uk-UA.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](README.ar.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](README.ja.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](README.vi.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](README.bg.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](README.da.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](README.fi.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](README.he.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](README.hu.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](README.id.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](README.ko.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](README.ms.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](README.nl.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](README.no.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](README.pt.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](README.ro.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](README.pl.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](README.sk.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](README.sv.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](README.phi.md)
--- ### ๐Ÿค– Free AI Provider for your favorite coding agents _Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._
OpenClaw
OpenClaw
โญ 205K 		NanoBot
NanoBot
โญ 20.9K 		PicoClaw
PicoClaw
โญ 14.6K 		ZeroClaw
ZeroClaw
โญ 9.9K 		IronClaw
IronClaw
โญ 2.1K
OpenCode
OpenCode
โญ 106K 		Codex CLI
Codex CLI
โญ 60.8K 		Claude Code
Claude Code
โญ 67.3K 		Gemini CLI
Gemini CLI
โญ 94.7K 		Kilo Code
Kilo Code
โญ 15.5K
๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota --- ## ๐Ÿ“ง 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) - **Original Project**: [9router by decolua](https://github.com/decolua/9router) --- ## ๐Ÿค” Why OmniRoute? **Stop wasting money and hitting limits:** - Subscription quota expires unused every month - Rate limits stop you mid-coding - Expensive APIs ($20-50/month per provider) - Manual switching between providers **OmniRoute solves this:** - โœ… **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 - โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool --- ## ๐Ÿ”„ How It Works ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...) โ”‚ Tool โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ http://localhost:20128/v1 โ†“ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ OmniRoute (Smart Router) โ”‚ โ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚ โ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚ โ”‚ โ€ข Auto token refresh โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”œโ”€โ†’ [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] iFlow, Qwen, Kiro (unlimited) Result: Never stop coding, minimal cost ``` --- ## ๐ŸŽฏ What OmniRoute Solves โ€” 16 Real Pain Points > **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to zero observability.
๐Ÿ’ธ 1. "I pay for an expensive subscription but still get interrupted by limits" Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity. **How OmniRoute solves it:** - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next - **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard
๐Ÿ”Œ 2. "I need to use multiple providers but each has a different API" OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints. **How OmniRoute solves it:** - **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 36+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE - **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content` - **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion - **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
๐ŸŒ 3. "My AI provider blocks my region/country" Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries. **How OmniRoute solves it:** - **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key - **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP - **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory` - **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass) - **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing - **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection
๐Ÿ†“ 4. "I want to use AI for coding but I have no money" Not everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost. **How OmniRoute solves it:** - **Free Tier Providers Built-in** โ€” Native support for 100% free providers: iFlow (8 unlimited models), Qwen (3 unlimited models), Kiro (Claude for free), Gemini CLI (180K/month free) - **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime - **NVIDIA NIM Free Credits** โ€” 1000 free credits integrated - **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider
๐Ÿ”’ 5. "I need to protect my AI gateway from unauthorized access" When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse. **How OmniRoute solves it:** - **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page - **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle - **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing - **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens - **Rate Limiter** โ€” Per-IP rate limiting with configurable windows - **IP Filtering** โ€” Allowlist/blocklist for access control - **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns - **AES-256-GCM Encryption** โ€” Credentials encrypted at rest
๐Ÿ›‘ 6. "My provider went down and I lost my coding flow" AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application. **How OmniRoute solves it:** - **Circuit Breaker per-provider** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open) - **Exponential Backoff** โ€” Progressive retry delays - **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms - **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention - **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain - **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
๐Ÿ”ง 7. "Configuring each AI tool is tedious and repetitive" Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. **How OmniRoute solves it:** - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users - **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 36+ providers
๐Ÿ”‘ 8. "Managing OAuth tokens from multiple providers is hell" Claude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic. **How OmniRoute solves it:** - **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration - **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow - **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction - **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers - **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility - **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker
๐Ÿ“Š 9. "I don't know how much I'm spending or where" Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up. **How OmniRoute solves it:** - **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider - **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback - **Per-Model Pricing Configuration** โ€” Configurable prices per model - **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key - **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency
๐Ÿ› 10. "I can't diagnose errors and problems in AI calls" When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error. **How OmniRoute solves it:** - **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console - **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing - **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation
๐Ÿ—๏ธ 11. "Deploying and maintaining the gateway is complex" Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction. **How OmniRoute solves it:** - **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done - **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi) - **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw) - **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode - **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking) - **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers - **DB Backups** โ€” Automatic backup, restore, export and import of all settings
๐ŸŒ 12. "The interface is English-only and my team doesn't speak English" Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors. **How OmniRoute solves it:** - **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English - **RTL Support** โ€” Right-to-left support for Arabic and Hebrew - **Multi-Language READMEs** โ€” 30 complete documentation translations - **Language Selector** โ€” Globe icon in header for real-time switching
๐Ÿ”„ 13. "I need more than chat โ€” I need embeddings, images, audio" AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format. **How OmniRoute solves it:** - **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models - **Image Generation** โ€” `/v1/images/generations` with 4 providers and 9+ models - **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper-compatible - **Text-to-Speech** โ€” `/v1/audio/speech` โ€” Multi-provider audio synthesis - **Moderations** โ€” `/v1/moderations` โ€” Content safety checks - **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking - **Responses API** โ€” Full `/v1/responses` support for Codex
๐Ÿงช 14. "I have no way to test and compare quality across models" Developers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist. **How OmniRoute solves it:** - **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal - **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function) - **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison - **Chat Tester** โ€” Full round-trip with visual response rendering - **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy
๐Ÿ“ˆ 15. "I need to scale without losing performance" As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected. **How OmniRoute solves it:** - **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency - **Request Idempotency** โ€” 5s deduplication window for identical requests - **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking - **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence - **API Key Validation Cache** โ€” 3-tier cache for production performance - **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime
๐Ÿค– 16. "I want to control model behavior globally" Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical. **How OmniRoute solves it:** - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) - **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click - **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing
--- ## โšก Quick Start **1. Install globally:** ```bash npm install -g omniroute omniroute ``` ๐ŸŽ‰ Dashboard opens at `http://localhost:20128` | Command | Description | | ----------------------- | ----------------------------------------------------------- | | `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) | | `omniroute --port 3000` | Set canonical/API port to 3000 | | `omniroute --no-open` | Don't auto-open browser | | `omniroute --help` | Show help | Optional split-port mode: ```bash PORT=20128 DASHBOARD_PORT=20129 omniroute # API: http://localhost:20128/v1 # Dashboard: http://localhost:20129 ``` When ports are split, the API port serves only OpenAI-compatible routes (`/v1`, `/chat/completions`, `/responses`, `/models`, `/codex/*`). **2. Connect a FREE provider:** Dashboard โ†’ Providers โ†’ Connect **Claude Code** or **Antigravity** โ†’ OAuth login โ†’ Done! **3. Use in your CLI tool:** ``` Claude Code/Codex/Gemini CLI/OpenClaw/Cursor/Cline Settings: Endpoint: http://localhost:20128/v1 API Key: [copy from dashboard] Model: if/kimi-k2-thinking ``` **That's it!** Start coding with FREE AI models. **Alternative โ€” run from source:** ```bash cp .env.example .env npm install PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev ``` --- ## ๐Ÿณ 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 \ -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 \ --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 ``` | Image | Tag | Size | Description | | ------------------------ | -------- | ------ | --------------------- | | `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release | | `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version | --- ## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On > ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux. Run OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes: - ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration - ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login - ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues - โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux) - ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server ### Quick Start ```bash # Development mode npm run electron:dev # Build for your platform npm run electron:build # Current platform npm run electron:build:win # Windows (.exe) npm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64 npm run electron:build:linux # Linux (.AppImage) ``` ### System Tray When minimized, OmniRoute lives in your system tray with quick actions: - Open dashboard - Change server port - Quit application ๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.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** (1000 credits) | One-time | Free tier testing | | | DeepSeek | Pay-per-use | None | Best price/quality | | | Groq | Free tier + paid | Rate limited | Ultra-fast inference | | | xAI (Grok) | Pay-per-use | None | Grok models | | | Mistral | Free tier + paid | Rate limited | European AI | | | OpenRouter | Pay-per-use | None | 100+ models | | **๐Ÿ’ฐ CHEAP** | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | | | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | | | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | | **๐Ÿ†“ FREE** | iFlow | $0 | Unlimited | 8 models free | | | Qwen | $0 | Unlimited | 3 models free | | | Kiro | $0 | Unlimited | Claude free | **๐Ÿ’ก Pro Tip:** Start with Gemini CLI (180K free/month) + iFlow (unlimited free) combo = $0 cost! --- ## ๐Ÿ’ก Key Features ### ๐Ÿง  Core Routing & Intelligence | Feature | What It Does | | ------------------------------- | ------------------------------------------------------------------------------ | | ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free | | ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider | | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Cursor โ†” Kiro seamless + response sanitization | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | | ๐ŸŽจ **Custom Combos** | 6 strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized | | ๐Ÿงฉ **Custom Models** | Add any model ID to any provider | | ๐ŸŒ **Wildcard Router** | Route `provider/*` patterns to any provider dynamically | | ๐Ÿง  **Thinking Budget** | Passthrough, auto, custom, and adaptive modes for reasoning models | | ๐Ÿ’ฌ **System Prompt Injection** | Global system prompt applied across all requests | | ๐Ÿ“„ **Responses API** | Full OpenAI Responses API (`/v1/responses`) support for Codex | ### ๐ŸŽต Multi-Modal APIs | Feature | What It Does | | -------------------------- | --------------------------------------------------- | | ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` โ€” 4 providers, 9+ models | | ๐Ÿ“ **Embeddings** | `/v1/embeddings` โ€” 6 providers, 9+ models | | ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” Whisper-compatible | | ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” Multi-provider audio synthesis | | ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` โ€” Content safety checks | | ๐Ÿ”€ **Reranking** | `/v1/rerank` โ€” Document relevance reranking | ### ๐Ÿ›ก๏ธ Resilience & Security | Feature | What It Does | | ------------------------------- | ----------------------------------------------------------------------------- | | ๐Ÿ”Œ **Circuit Breaker** | Auto-open/close per-provider with configurable thresholds | | ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore rate-limit for API key providers | | ๐Ÿง  **Semantic Cache** | Two-tier cache (signature + semantic) reduces cost & latency | | โšก **Request Idempotency** | 5s dedup window for duplicate requests | | ๐Ÿ”’ **TLS Fingerprint Spoofing** | Bypass TLS-based bot detection via wreq-js | | ๐ŸŒ **IP Filtering** | Allowlist/blocklist for API access control | | ๐Ÿ“Š **Editable Rate Limits** | Configurable RPM, min gap, and max concurrent at system level | | ๐Ÿ›ก **API Endpoint Protection** | Auth gating + provider blocking for the `/models` endpoint | | ๐Ÿ”’ **Proxy Visibility** | Color-coded badges: ๐ŸŸข global, ๐ŸŸก provider, ๐Ÿ”ต per-connection with IP display | | ๐ŸŒ **3-Level Proxy Config** | Configure proxies at global, per-provider, or per-connection level | ### ๐Ÿ“Š Observability & Analytics | Feature | What It Does | | -------------------------- | ---------------------------------------------------------------------- | | ๐Ÿ“ **Request Logging** | Debug mode with full request/response logs | | ๐Ÿ’พ **SQLite Proxy Logs** | Persistent proxy logs survive server restarts | | ๐Ÿ“Š **Analytics Dashboard** | Recharts-powered: stat cards, model usage chart, provider table | | ๐Ÿ“ˆ **Progress Tracking** | Opt-in SSE progress events for streaming | | ๐Ÿงช **LLM Evaluations** | Golden set testing with 4 match strategies | | ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency aggregation + X-Request-Id tracing | | ๐Ÿ“‹ **Logs Dashboard** | Unified 4-tab page: Request Logs, Proxy Logs, Audit Logs, Console | | ๐Ÿ–ฅ๏ธ **Console Log Viewer** | Real-time terminal-style viewer with level filter, search, auto-scroll | | ๐Ÿ“‘ **File-Based Logging** | Console interceptor captures all output to JSON log file with rotation | | ๐Ÿฅ **Health Dashboard** | System uptime, circuit breaker states, lockouts, cache stats | | ๐Ÿ’ฐ **Cost Tracking** | Budget management + per-model pricing configuration | ### โ˜๏ธ Deployment & Sync | Feature | What It Does | | ---------------------------- | --------------------------------------------------------------------- | | ๐Ÿ’พ **Cloud Sync** | Sync config across devices via Cloudflare Workers | | ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloudflare Workers | | ๐Ÿ”‘ **API Key Management** | Generate, rotate, and scope API keys per provider | | ๐Ÿง™ **Onboarding Wizard** | 4-step guided setup for first-time users | | ๐Ÿ”ง **CLI Tools Dashboard** | One-click configure Claude, Codex, Cline, OpenClaw, Kilo, Antigravity | | ๐Ÿ”„ **DB Backups** | Automatic backup, restore, export & import for all settings | | ๐ŸŒ **Internationalization** | Full i18n with next-intl โ€” 30 languages including RTL support | | ๐ŸŒ **Language Selector** | Globe icon in header for real-time switching between 30 languages | | ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` env var to override default `~/.omniroute` storage path |
๐Ÿ“– Feature Details ### ๐ŸŽฏ Smart 4-Tier Fallback Create combos with automatic fallback: ``` Combo: "my-coding-stack" 1. cc/claude-opus-4-6 (your subscription) 2. nvidia/llama-3.3-70b (free NVIDIA API) 3. glm/glm-4.7 (cheap backup, $0.6/1M) 4. if/kimi-k2-thinking (free fallback) โ†’ Auto switches when quota runs out or errors occur ``` ### ๐Ÿ“Š Real-Time Quota Tracking - Token consumption per provider - Reset countdown (5-hour, daily, weekly) - Cost estimation for paid tiers - Monthly spending reports ### ๐Ÿ”„ Format Translation Seamless translation between formats: - **OpenAI** โ†” **Claude** โ†” **Gemini** โ†” **OpenAI Responses** - Your CLI tool sends OpenAI format โ†’ OmniRoute translates โ†’ Provider receives native format - Works with any tool that supports custom OpenAI endpoints - **Response sanitization** โ€” Strips non-standard fields for strict OpenAI SDK compatibility - **Role normalization** โ€” `developer` โ†’ `system` for non-OpenAI; `system` โ†’ `user` for GLM/ERNIE models - **Think tag extraction** โ€” `` blocks โ†’ `reasoning_content` for thinking models - **Structured output** โ€” `json_schema` โ†’ Gemini's `responseMimeType`/`responseSchema` ### ๐Ÿ‘ฅ Multi-Account Support - Add multiple accounts per provider - Auto round-robin or priority-based routing - Fallback to next account when one hits quota ### ๐Ÿ”„ Auto Token Refresh - OAuth tokens automatically refresh before expiration - No manual re-authentication needed - Seamless experience across all providers ### ๐ŸŽจ Custom Combos - Create unlimited model combinations - 6 strategies: fill-first, round-robin, power-of-two-choices, random, least-used, cost-optimized - Share combos across devices with Cloud Sync ### ๐Ÿฅ Health Dashboard - System status (uptime, version, memory usage) - Circuit breaker states per provider (Closed/Open/Half-Open) - Rate limit status and active lockouts - Signature cache statistics - Latency telemetry (p50/p95/p99) + prompt cache - Reset health status with one click ### ๐Ÿ”ง Translator Playground OmniRoute includes a powerful built-in Translator Playground with **4 modes** for debugging, testing, and monitoring API translations: | Mode | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **๐Ÿ’ป Playground** | Direct format translation โ€” paste any API request body and instantly see how OmniRoute translates it between provider formats (OpenAI โ†” Claude โ†” Gemini โ†” Responses API). Includes example templates and format auto-detection. | | **๐Ÿ’ฌ Chat Tester** | Send real chat requests through OmniRoute and see the full round-trip: your input, the translated request, the provider response, and the translated response back. Invaluable for validating combo routing. | | **๐Ÿงช Test Bench** | Batch testing mode โ€” define multiple test cases with different inputs and expected outputs, run them all at once, and compare results across providers and models. | | **๐Ÿ“ฑ Live Monitor** | Real-time request monitoring โ€” watch incoming requests as they flow through OmniRoute, see format translations happening live, and identify issues instantly. | **Access:** Dashboard โ†’ Translator (sidebar) ### ๐Ÿ’พ Cloud Sync - Sync providers, combos, and settings across devices - Automatic background sync - Secure encrypted storage
--- ## ๐ŸŽฏ Use Cases ### Case 1: "I have Claude Pro subscription" **Problem:** Quota expires unused, rate limits during heavy coding ``` Combo: "maximize-claude" 1. cc/claude-opus-4-6 (use subscription fully) 2. glm/glm-4.7 (cheap backup when quota out) 3. if/kimi-k2-thinking (free emergency fallback) Monthly cost: $20 (subscription) + ~$5 (backup) = $25 total vs. $20 + hitting limits = frustration ``` ### Case 2: "I want zero cost" **Problem:** Can't afford subscriptions, need reliable AI coding ``` Combo: "free-forever" 1. gc/gemini-3-flash (180K free/month) 2. if/kimi-k2-thinking (unlimited free) 3. qw/qwen3-coder-plus (unlimited free) Monthly cost: $0 Quality: Production-ready models ``` ### Case 3: "I need 24/7 coding, no interruptions" **Problem:** Deadlines, can't afford downtime ``` Combo: "always-on" 1. cc/claude-opus-4-6 (best quality) 2. cx/gpt-5.2-codex (second subscription) 3. glm/glm-4.7 (cheap, resets daily) 4. minimax/MiniMax-M2.1 (cheapest, 5h reset) 5. if/kimi-k2-thinking (free unlimited) Result: 5 layers of fallback = zero downtime ``` ### Case 4: "I want FREE AI in OpenClaw" **Problem:** Need AI assistant in messaging apps, completely free ``` Combo: "openclaw-free" 1. if/glm-4.7 (unlimited free) 2. if/minimax-m2.1 (unlimited free) 3. if/kimi-k2-thinking (unlimited free) Monthly cost: $0 Access via: WhatsApp, Telegram, Slack, Discord, iMessage, Signal... ``` --- ## ๐Ÿ“– Setup Guide
๐Ÿ’ณ Subscription Providers ### Claude Code (Pro/Max) ```bash Dashboard โ†’ Providers โ†’ Connect Claude Code โ†’ OAuth login โ†’ Auto token refresh โ†’ 5-hour + weekly quota tracking Models: cc/claude-opus-4-6 cc/claude-sonnet-4-5-20250929 cc/claude-haiku-4-5-20251001 ``` **Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) ```bash Dashboard โ†’ Providers โ†’ Connect Codex โ†’ OAuth login (port 1455) โ†’ 5-hour + weekly reset Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` ### Gemini CLI (FREE 180K/month!) ```bash Dashboard โ†’ Providers โ†’ Connect Gemini CLI โ†’ Google OAuth โ†’ 180K completions/month + 1K/day Models: gc/gemini-3-flash-preview gc/gemini-2.5-pro ``` **Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot ```bash Dashboard โ†’ Providers โ†’ Connect GitHub โ†’ OAuth via GitHub โ†’ Monthly reset (1st of month) Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro ```
๐Ÿ”‘ API Key Providers ### NVIDIA NIM (FREE 1000 credits!) 1. Sign up: [build.nvidia.com](https://build.nvidia.com) 2. Get free API key (1000 inference credits included) 3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM: - API Key: `nvapi-your-key` **Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more **Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation! ### DeepSeek 1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) 2. Get API key 3. Dashboard โ†’ Add Provider โ†’ DeepSeek **Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` ### Groq (Free Tier Available!) 1. Sign up: [console.groq.com](https://console.groq.com) 2. Get API key (free tier included) 3. Dashboard โ†’ Add Provider โ†’ Groq **Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` **Pro Tip:** Ultra-fast inference โ€” best for real-time coding! ### OpenRouter (100+ Models) 1. Sign up: [openrouter.ai](https://openrouter.ai) 2. Get API key 3. Dashboard โ†’ Add Provider โ†’ OpenRouter **Models:** Access 100+ models from all major providers through a single API key.
๐Ÿ’ฐ Cheap Providers (Backup) ### GLM-4.7 (Daily reset, $0.6/1M) 1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) 2. Get API key from Coding Plan 3. Dashboard โ†’ Add API Key: - Provider: `glm` - API Key: `your-key` **Use:** `glm/glm-4.7` **Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM. ### MiniMax M2.1 (5h reset, $0.20/1M) 1. Sign up: [MiniMax](https://www.minimax.io/) 2. Get API key 3. Dashboard โ†’ Add API Key **Use:** `minimax/MiniMax-M2.1` **Pro Tip:** Cheapest option for long context (1M tokens)! ### Kimi K2 ($9/month flat) 1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) 2. Get API key 3. Dashboard โ†’ Add API Key **Use:** `kimi/kimi-latest` **Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
๐Ÿ†“ FREE Providers (Emergency Backup) ### iFlow (8 FREE models) ```bash Dashboard โ†’ Connect iFlow โ†’ iFlow OAuth login โ†’ Unlimited usage Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 if/minimax-m2 if/deepseek-r1 ``` ### Qwen (3 FREE models) ```bash Dashboard โ†’ Connect Qwen โ†’ Device code authorization โ†’ Unlimited usage Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` ### Kiro (Claude FREE) ```bash Dashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited usage Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ```
๐ŸŽจ Create Combos ### Example 1: Maximize Subscription โ†’ Cheap Backup ``` Dashboard โ†’ Combos โ†’ Create New Name: premium-coding Models: 1. cc/claude-opus-4-6 (Subscription primary) 2. glm/glm-4.7 (Cheap backup, $0.6/1M) 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) Use in CLI: premium-coding ``` ### Example 2: Free-Only (Zero Cost) ``` Name: free-combo Models: 1. gc/gemini-3-flash-preview (180K free/month) 2. if/kimi-k2-thinking (unlimited) 3. qw/qwen3-coder-plus (unlimited) Cost: $0 forever! ```
๐Ÿ”ง CLI Integration ### Cursor IDE ``` Settings โ†’ Models โ†’ Advanced: OpenAI API Base URL: http://localhost:20128/v1 OpenAI API Key: [from OmniRoute dashboard] Model: cc/claude-opus-4-6 ``` ### Claude Code Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI ```bash export OPENAI_BASE_URL="http://localhost:20128" export OPENAI_API_KEY="your-omniroute-api-key" codex "your prompt" ``` ### OpenClaw **Option 1 โ€” Dashboard (recommended):** ``` Dashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply ``` **Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`: ```json { "models": { "providers": { "omniroute": { "baseUrl": "http://127.0.0.1:20128/v1", "apiKey": "sk_omniroute", "api": "openai-completions" } } } } ``` > **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode ``` Settings โ†’ API Configuration: Provider: OpenAI Compatible Base URL: http://localhost:20128/v1 API Key: [from OmniRoute dashboard] Model: if/kimi-k2-thinking ```
--- ## ๐Ÿงช 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 10 test cases covering: - Greetings, math, geography, code generation - JSON format compliance, translation, markdown - 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` | --- ## ๐Ÿ› Troubleshooting
Click to expand troubleshooting guide **"Language model did not provide messages"** - Provider quota exhausted โ†’ Check dashboard quota tracker - Solution: Use combo fallback or switch to cheaper tier **Rate limiting** - Subscription quota out โ†’ Fallback to GLM/MiniMax - Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking` **OAuth token expired** - Auto-refreshed by OmniRoute - If issues persist: Dashboard โ†’ Provider โ†’ Reconnect **High costs** - Check usage stats in Dashboard โ†’ Costs - Switch primary model to GLM/MiniMax - Use free tier (Gemini CLI, iFlow) for non-critical tasks **Dashboard/API ports are wrong** - `PORT` is the canonical base port (and API port by default) - `API_PORT` overrides only OpenAI-compatible API listener - `DASHBOARD_PORT` overrides only dashboard/Next.js listener - Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks) **Cloud sync errors** - Verify `BASE_URL` points to your running instance - Verify `CLOUD_URL` points to your expected cloud endpoint - Keep `NEXT_PUBLIC_*` values aligned with server-side values **First login not working** - Check `INITIAL_PASSWORD` in `.env` - If unset, fallback password is `123456` **No request logs** - Set `ENABLE_REQUEST_LOGS=true` in `.env` **Connection test shows "Invalid" for OpenAI-compatible providers** - Many providers don't expose a `/models` endpoint - OmniRoute v1.0.6+ includes fallback validation via chat completions - Ensure base URL includes `/v1` suffix ### ๐Ÿ” OAuth em Servidor Remoto (Remote OAuth Setup) > **โš ๏ธ IMPORTANTE para usuรกrios com OmniRoute em VPS/Docker/servidor remoto** #### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo. As credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com: ``` Error 400: redirect_uri_mismatch ``` #### Soluรงรฃo: Configure suas prรณprias credenciais OAuth Vocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. #### Passo a passo **1. Acesse o Google Cloud Console** Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) **2. Crie um novo OAuth 2.0 Client ID** - Clique em **"+ Create Credentials"** โ†’ **"OAuth client ID"** - Tipo de aplicativo: **"Web application"** - Nome: escolha qualquer nome (ex: `OmniRoute Remote`) **3. Adicione as Authorized Redirect URIs** No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` > Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`). **4. Salve e copie as credenciais** Apรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**. **5. Configure as variรกveis de ambiente** No seu `.env` (ou nas variรกveis de ambiente do Docker): ```bash # Para Antigravity: ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret # Para Gemini CLI: GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` **6. Reinicie o OmniRoute** ```bash # Se usando npm: npm run dev # Se usando Docker: docker restart omniroute ``` **7. Tente conectar novamente** Dashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth Agora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก. --- #### Workaround temporรกrio (sem configurar credenciais prรณprias) Se nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**: 1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google 2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto) 3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue) 4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute 5. Clique em **"Connect"** > Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.
--- ## ๐Ÿ› ๏ธ Tech Stack - **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible) - **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (v1.0.6) - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4 - **Database**: LowDB (JSON) + SQLite (domain state + proxy logs) - **Streaming**: Server-Sent Events (SSE) - **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys - **Testing**: Node.js test runner (368+ unit tests) - **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 --- ## ๐Ÿ“– Documentation | Document | Description | | -------------------------------------------- | ---------------------------------------------- | | [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment | | [API Reference](docs/API_REFERENCE.md) | All endpoints with examples | | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions | | [Architecture](docs/ARCHITECTURE.md) | System architecture and internals | | [Contributing](CONTRIBUTING.md) | Development setup and guidelines | | [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification | | [Security Policy](SECURITY.md) | Vulnerability reporting and security practices | | [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup | | [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots | ### ๐Ÿ“ธ Dashboard Preview
Click to see dashboard screenshots | 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) | | **Endpoint** | ![Endpoint](docs/screenshots/09-endpoint.png) |
--- ## ๐Ÿ—บ๏ธ Roadmap OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas: | Category | Planned Features | Highlights | | ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- | | ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection | | ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping | | ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model | | ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing | | โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API | | ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode | ### ๐Ÿ”œ Coming Soon - ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE - ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework - ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests - ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata - ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider > ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs) --- ## ๐Ÿ‘ฅ 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 v1.0.6 --title "v1.0.6" --generate-notes ``` --- ## ๐Ÿ“Š Star History Star History Chart --- ## ๐Ÿ™ 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)** โ€” the original Go implementation that inspired this JavaScript port. --- ## ๐Ÿ“„ License MIT License - see [LICENSE](LICENSE) for details. ---
Built with โค๏ธ for developers who code 24/7
omniroute.online