# ๐ 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. Now with **MCP & A2A** agent orchestration._
**Chat Completions โข Embeddings โข Image Generation โข Video โข Music โข Audio โข Reranking โข MCP Server โข A2A Protocol โข 100% TypeScript**
---
๐ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ one config, unlimited models and quota
---
## ๐ค 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
---
## ๐ง 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)
---
## ๐ 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 โ 30 Real Pain Points & Use Cases
> **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 protocol operations and enterprise 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 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI)
- **Text-to-Video** โ `/v1/videos/generations` โ ComfyUI (AnimateDiff, SVD) and SD WebUI
- **Text-to-Music** โ `/v1/music/generations` โ ComfyUI (Stable Audio Open, MusicGen)
- **Audio Transcription** โ `/v1/audio/transcriptions` โ Whisper + Nvidia NIM, HuggingFace, Qwen3
- **Text-to-Speech** โ `/v1/audio/speech` โ ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, + existing providers
- **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
๐งฐ 17. "I need MCP tools as first-class product capabilities"
Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer.
**How OmniRoute solves it:**
- MCP appears in the dashboard navigation and endpoint protocol tab
- Dedicated MCP management page with process, tools, scopes, and audit
- Built-in quick-start for `omniroute --mcp` and client onboarding
๐ง 18. "I need A2A orchestration with sync + stream task paths"
Agent workflows need both direct replies and long-running streamed execution with lifecycle control.
**How OmniRoute solves it:**
- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream`
- SSE streaming with terminal state propagation
- Task lifecycle APIs for `tasks/get` and `tasks/cancel`
๐ฐ๏ธ 19. "I need real MCP process health, not guessed status"
Operational teams need to know if MCP is actually alive, not just whether an API is reachable.
**How OmniRoute solves it:**
- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode
- MCP status API combining heartbeat + recent activity
- UI status cards for process/uptime/heartbeat freshness
๐ 20. "I need auditable MCP tool execution"
When tools mutate config or trigger ops actions, teams need forensic traceability.
**How OmniRoute solves it:**
- SQLite-backed audit logging for MCP tool calls
- Filters by tool, success/failure, API key, and pagination
- Dashboard audit table + stats endpoints for automation
๐ 21. "I need scoped MCP permissions per integration"
Different clients should have least-privilege access to tool categories.
**How OmniRoute solves it:**
- 9 granular MCP scopes for controlled tool access
- Scope enforcement and visibility in MCP management UI
- Safe default posture for operational tooling
โ๏ธ 22. "I need operational controls without redeploying"
Teams need quick runtime changes during incidents or cost events.
**How OmniRoute solves it:**
- Switch combo activation directly from MCP dashboard
- Apply resilience profiles from pre-defined policy packs
- Reset circuit breaker state from the same operations panel
๐ 23. "I need live A2A task lifecycle visibility and cancellation"
Without lifecycle visibility, task incidents become hard to triage.
**How OmniRoute solves it:**
- Task listing/filtering by state/skill with pagination
- Drill-down on task metadata, events, and artifacts
- Task cancellation endpoint and UI action with confirmation
๐ 24. "I need active stream metrics for A2A load"
Streaming workflows require operational insight into concurrency and live connections.
**How OmniRoute solves it:**
- Active stream counters integrated into A2A status
- Last task timestamp and per-state counts
- A2A dashboard cards for real-time ops monitoring
๐ชช 25. "I need standard agent discovery for clients"
External clients and orchestrators need machine-readable metadata for onboarding.
**How OmniRoute solves it:**
- Agent Card exposed at `/.well-known/agent.json`
- Capabilities and skills shown in management UI
- A2A status API includes discovery metadata for automation
๐งญ 26. "I need protocol discoverability in the product UX"
If users cannot discover protocol surfaces, adoption and support quality drop.
**How OmniRoute solves it:**
- Sidebar entries for MCP and A2A
- Endpoint page Protocols tab with quick-start and status
- Links from overview to dedicated management dashboards
๐งช 27. "I need end-to-end protocol validation with real clients"
Mock tests are not enough to validate protocol compatibility before release.
**How OmniRoute solves it:**
- E2E suite that boots app and uses real MCP SDK client transport
- A2A client tests for discovery, send, stream, get, and cancel flows
- Cross-check assertions against MCP audit and A2A tasks APIs
๐ก 28. "I need unified observability across all interfaces"
Splitting observability by protocol creates blind spots and longer MTTR.
**How OmniRoute solves it:**
- Unified dashboards/logs/analytics in one product
- Health + audit + request telemetry across OpenAI, MCP, and A2A layers
- Operational APIs for status and automation
๐ผ 29. "I need one runtime for proxy + tools + agent orchestration"
Running many separate services increases operational cost and failure modes.
**How OmniRoute solves it:**
- OpenAI-compatible proxy, MCP server, and A2A server in one stack
- Shared auth, resilience, data store, and observability
- Consistent policy model across all interaction surfaces
๐ 30. "I need to ship agentic workflows without glue-code sprawl"
Teams lose velocity when stitching multiple ad-hoc services and scripts.
**How OmniRoute solves it:**
- Unified endpoint strategy for clients and agents
- Built-in protocol management UIs and smoke validation paths
- Production-ready foundations (security, logging, resilience, backup)
### Example Playbooks (Integrated Use Cases)
**Playbook A: Maximize paid subscription + cheap backup**
```txt
Combo: "maximize-claude"
1. cc/claude-opus-4-6
2. glm/glm-4.7
3. if/kimi-k2-thinking
Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```
**Playbook B: Zero-cost coding stack**
```txt
Combo: "free-forever"
1. gc/gemini-3-flash
2. if/kimi-k2-thinking
3. qw/qwen3-coder-plus
Monthly cost: $0
Outcome: stable free coding workflow
```
**Playbook C: 24/7 always-on fallback chain**
```txt
Combo: "always-on"
1. cc/claude-opus-4-6
2. cx/gpt-5.2-codex
3. glm/glm-4.7
4. minimax/MiniMax-M2.1
5. if/kimi-k2-thinking
Outcome: deep fallback depth for deadline-critical workloads
```
**Playbook D: Agent ops with MCP + A2A**
```txt
1) Start MCP transport (`omniroute --mcp`) for tool-driven operations
2) Run A2A tasks via `message/send` and `message/stream`
3) Observe via /dashboard/mcp and /dashboard/a2a
4) Control incidents with resilience profile + task cancellation
```
---
## โก Quick Start
### 1) Install and run
```bash
npm install -g omniroute
omniroute
```
Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`.
| Command | Description |
| ----------------------- | ----------------------------------------------------------- |
| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) |
| `omniroute --port 3000` | Set canonical/API port to 3000 |
| `omniroute --mcp` | Start MCP server (stdio transport) |
| `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
```
### 2) Connect providers and create your API key
1. Open Dashboard โ `Providers` and connect at least one provider (OAuth or API key).
2. Open Dashboard โ `Endpoint` and create an API key.
3. (Optional) Open Dashboard โ `Combos` and set your fallback chain.
### 3) Point your coding tool to OmniRoute
```txt
Base URL: http://localhost:20128/v1
API Key: [copy from Endpoint page]
Model: if/kimi-k2-thinking (or any provider/model prefix)
```
Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs.
### 4) Enable and validate protocols (v2.0)
**MCP (for tool-driven operations):**
```bash
omniroute --mcp
```
Then connect your MCP client over `stdio` and test tools like:
- `omniroute_get_health`
- `omniroute_list_combos`
**A2A (for agent-to-agent workflows):**
```bash
curl http://localhost:20128/.well-known/agent.json
```
```bash
curl -X POST http://localhost:20128/a2a \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}'
```
### 5) Validate everything end-to-end (recommended)
```bash
npm run test:protocols:e2e
```
This suite validates real MCP and A2A client flows against a running app.
### 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
OmniRoute v2.0 is built as an operational platform, not just a relay proxy.
### ๐ค Agent & Protocol Operations (v2.0)
| Feature | What It Does |
| ------------------------------------ | -------------------------------------------------------------------------------- |
| ๐ง **MCP Server (16 tools)** | IDE/agent tools control routing, health, combos, limits, and operations |
| ๐ค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows |
| ๐งญ **MCP/A2A Dashboards** | Dedicated management pages (`/dashboard/mcp`, `/dashboard/a2a`) |
| ๐ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) |
| ๐ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution |
| ๐ **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access |
| ๐ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks |
| ๐ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery |
| ๐งช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` |
| โ๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface |
### ๐ง 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 โ Responses with schema-safe conversions |
| ๐ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection |
| ๐ **Auto Token Refresh** | OAuth tokens refresh automatically with retry |
| ๐จ **Custom Combos** | 6 balancing strategies + fallback chain control |
| ๐ **Wildcard Router** | `provider/*` dynamic routing |
| ๐ง **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits |
| ๐ **Model Aliases** | Built-in + custom model aliasing and migration safety |
| โก **Background Degradation** | Route low-priority background tasks to cheaper models |
| ๐ฌ **System Prompt Injection** | Global behavior controls applied consistently |
| ๐ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows |
### ๐ต Multi-Modal APIs
| Feature | What It Does |
| -------------------------- | ------------------------------------------------------------- |
| ๐ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends |
| ๐ **Embeddings** | `/v1/embeddings` for search and RAG pipelines |
| ๐ค **Audio Transcription** | `/v1/audio/transcriptions` (Whisper and additional providers) |
| ๐ **Text-to-Speech** | `/v1/audio/speech` (multiple engines/providers) |
| ๐ฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) |
| ๐ต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) |
| ๐ก๏ธ **Moderations** | `/v1/moderations` safety checks |
| ๐ **Reranking** | `/v1/rerank` for relevance scoring |
### ๐ก๏ธ Resilience, Security & Governance
| Feature | What It Does |
| ----------------------------------- | ---------------------------------------------------------- |
| ๐ **Circuit Breakers** | Provider-level trip/recover with threshold controls |
| ๐ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events |
| ๐ง **Semantic + Signature Cache** | Cost/latency reduction with two cache layers |
| โก **Request Idempotency** | Duplicate protection window |
| ๐ **TLS Fingerprint Spoofing** | Better compatibility with anti-bot filtered providers |
| ๐ **IP Filtering** | Allowlist/blocklist control for exposed deployments |
| ๐ **Editable Rate Limits** | Configurable global/provider-level limits with persistence |
| ๐ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls |
| ๐ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog |
### ๐ Observability & Analytics
| Feature | What It Does |
| ------------------------------- | ----------------------------------------------------- |
| ๐ **Request + Proxy Logging** | Full request/response and proxy logging |
| ๐ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page |
| ๐ **Request Telemetry** | p50/p95/p99 latency and request tracing |
| ๐ฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats |
| ๐ฐ **Cost Tracking** | Budget controls and per-model pricing visibility |
| ๐ **Analytics Visualizations** | Model/provider usage insights and trend views |
| ๐งช **Evaluation Framework** | Golden set testing with configurable match strategies |
### โ๏ธ Deployment & Platform
| Feature | What It Does |
| ---------------------------- | -------------------------------------------------------- |
| ๐ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments |
| ๐พ **Cloud Sync** | Configuration sync via cloud worker |
| ๐ **Backup/Restore** | Export/import and disaster recovery flows |
| ๐ง **Onboarding Wizard** | First-run guided setup |
| ๐ง **CLI Tools Dashboard** | One-click setup for popular coding tools |
| ๐ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage |
| ๐ **Custom Data Directory** | `DATA_DIR` override for storage location |
### Feature Deep Dive
#### Smart fallback with practical cost control
```txt
Combo: "my-coding-stack"
1. cc/claude-opus-4-6
2. nvidia/llama-3.3-70b
3. glm/glm-4.7
4. if/kimi-k2-thinking
```
When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching.
#### Protocol management that is visible and operable
- MCP + A2A are discoverable in UI and docs (not hidden)
- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`)
- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation)
#### Translator + validation workflow
The Translator area includes:
- **Playground**: request transformation checks
- **Chat Tester**: full request/response round-trip
- **Test Bench**: multiple cases in one run
- **Live Monitor**: real-time traffic view
Plus protocol validation with real clients via `npm run test:protocols:e2e`.
> ๐ **[MCP Server README](open-sse/mcp-server/README.md)** โ Tool reference, IDE configs, and client examples
>
> ๐ **[A2A Server README](src/lib/a2a/README.md)** โ Skills, JSON-RPC methods, streaming, and task lifecycle
## ๐งช 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
### Protocol Setup (MCP + A2A)
๐งฉ MCP Setup (Model Context Protocol)
Start MCP transport in stdio mode:
```bash
omniroute --mcp
```
Recommended validation flow:
1. Connect your MCP client over stdio.
2. Run `omniroute_get_health`.
3. Run `omniroute_list_combos`.
4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit.
Useful APIs for automation:
- `GET /api/mcp/status`
- `GET /api/mcp/tools`
- `GET /api/mcp/audit`
- `GET /api/mcp/audit/stats`
๐ค A2A Setup (Agent2Agent)
Discover the agent:
```bash
curl http://localhost:20128/.well-known/agent.json
```
Send a task:
```bash
curl -X POST http://localhost:20128/a2a \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'
```
Manage lifecycle:
- `GET /api/a2a/status`
- `GET /api/a2a/tasks`
- `GET /api/a2a/tasks/:id`
- `POST /api/a2a/tasks/:id/cancel`
Operational UI:
- `/dashboard/a2a` for task/state/stream observability and smoke actions
๐งช End-to-end protocol validation
Validate both protocols with real clients:
```bash
npm run test:protocols:e2e
```
This verifies:
- MCP SDK client connect/list/call
- A2A discovery/send/stream/get/cancel
- Cross-check data in MCP audit and A2A task management APIs
๐ณ 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
```
### OpenCode
**Step 1:** Add OmniRoute as a custom provider:
```bash
opencode
/connect
# Select "Other" โ Enter ID: "omniroute" โ Enter your OmniRoute API key
```
**Step 2:** Create/edit `opencode.json` in your project root:
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"omniroute": {
"npm": "@ai-sdk/openai-compatible",
"name": "OmniRoute",
"options": {
"baseURL": "http://localhost:20128/v1"
},
"models": {
"cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
"gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
"if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" }
}
}
}
}
```
**Step 3:** Select the model in OpenCode:
```bash
/models
# Select any OmniRoute model from the list
```
> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.
---
## ๐ 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
Click to expand tech stack details
- **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/` (zero `any` in core modules since v2.0)
- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4
- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions)
- **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)
- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E)
- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release)
- **Website**: [omniroute.online](https://omniroute.online)
- **Package**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute)
- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
---
## ๐ Documentation
| Document | Description |
| ---------------------------------------------- | --------------------------------------------------- |
| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients |
| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt |
| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing |
| [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 |
| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
---
## ๐บ๏ธ 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
[](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
---
## ๐ 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.
---
Subscription quota expires unused every month
-