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

Stop juggling 10 dashboards, dead API keys, and surprise bills.

┌──────────────────────────────────────────────────────────┐
│ Your IDE / CLI (Claude Code, Cursor, Cline...) │
└─────────────────────────┬──────────────────────────────────┘
 │ http://localhost:20128/v1
 ▼
┌──────────────────────────────────────────────────────────┐
│ OmniRoute — Smart Router │
│ RTK + Caveman compression · 14 routing strategies │
│ Circuit breakers · TLS stealth · MCP · A2A · Guardrails │
└─────────────────────────┬──────────────────────────────────┘
 ┌─────────────┬────┴────────┬─────────────┐
 ▼ Tier 1 ▼ Tier 2 ▼ Tier 3 ▼ Tier 4
 SUBSCRIPTION API KEY CHEAP FREE
 Claude Code, DeepSeek, GLM 0ドル.5, Kiro, Qoder,
 Codex, Copilot Groq, xAI MiniMax 0ドル.2 Pollinations
 quota out? ───▶ budget hit? ─▶ budget hit? ─▶ always on

A combo is a chain of models OmniRoute routes across automatically. Quota runs out, a provider fails, or costs spike — the combo silently slides to the next model. This is what makes OmniRoute unbreakable. 🛡️

No combo to create. Set your model to auto (or a variant) and OmniRoute builds a virtual combo from your connected providers, scored live:

_{The Auto-Combo engine scores every candidate on 9 factors (health, quota, cost, latency, success rate, freshness...) — see docs/routing/AUTO-COMBO.md.}

Combo: "always-on" Strategy: priority
 1. cc/claude-opus-4-7 ← subscription (use it fully)
 2. cx/gpt-5.5 ← second subscription
 3. glm/glm-5.1 ← cheap backup (0ドル.5/1M)
 4. kr/claude-sonnet-4.5 ← FREE, unlimited (never fails)
Result: 4 layers of fallback = zero downtime

_{📖 Auto-Combo Engine · Resilience Guide}

_{📊 Detailed comparison vs LiteLLM, OpenRouter & Portkey → docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md}

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

Same app, your machine, your rules. From a global npm install to your phone via Termux.

_{📖 Docker Guide · Desktop · Termux · PWA · OpenCode}

Your keys, your machine, your data. OmniRoute is a local proxy — it never phones home.

• 🏠 Runs 100% on your hardware — npm, Docker, desktop, or your phone. No OmniRoute cloud sits in the request path.
• 🔐 Credentials encrypted at rest — API keys & OAuth tokens sealed with AES-256-GCM.
• 🚫 Zero telemetry by default — your prompts go only to the providers you choose, nowhere else.
• 🛡️ Hardened gateway — API-key scoping, IP filtering, rate limits, prompt-injection guard, loopback-only process routes.
• 📜 MIT licensed & fully open-source — audit every line, self-host forever.

_{📖 Authorization · Guardrails · Compliance}

OmniRoute isn't just a server — it's a full command-line cockpit with 60+ commands, plus open agent protocols so an AI agent can drive OmniRoute by itself.

omniroute # serve gateway + dashboard (port 20128)
omniroute chat # interactive TUI chat client (slash: /model /combo /skill /memory)
omniroute setup # guided first-run wizard
omniroute doctor # diagnose providers, ports, native deps

Expose OmniRoute over MCP or A2A and any capable agent gets the keys to the whole gateway — routing, providers, combos, cache, compression, memory — autonomously.

# Give Claude Code the full OmniRoute toolset over MCP:
claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream

_{📖 MCP Server · A2A Server · Agent Protocols}

Why use many token when few token do trick? Every request passes through OmniRoute's compression pipeline transparently — no client changes. It stacks ideas from RTK and Caveman (⭐ 51K+).

Real example — Standard mode:

Before (69 tokens): "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."

After (19 tokens): "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."

Same answer. 72% fewer tokens. Zero accuracy loss. ✅

Client (10,000 tok) ──▶ OmniRoute Compression (7 options) ──▶ Provider (~1,080 tok, up to 95% saved)

Default stacked combo runs RTK → Caveman. When both act on the same tool/context payload, savings compound:

combined = 1 − (1 − RTK) ×ばつ (1 − Caveman_input)
average = 1 − (1 − 0.80) ×ばつ (1 − 0.46) = 89.2%
range = 78.4 – 94.6%

Code blocks, URLs, JSON and structured data are always protected by the preservation engine. Auto-trigger compression by token threshold, or assign a compression pipeline per routing combo.

📖 COMPRESSION_GUIDE.md · RTK_COMPRESSION.md · COMPRESSION_ENGINES.md

1) Install & run

npm install -g omniroute
omniroute

Dashboard at http://localhost:20128 · API at http://localhost:20128/v1.

2) Connect a FREE provider (no signup)

Dashboard → Providers → connect Kiro AI (free Claude unlimited) or OpenCode Free (no auth) → done.

3) Point your coding tool

Base URL: http://localhost:20128/v1
API Key: [copy from Dashboard → Endpoints]
Model: auto (zero-config smart routing — or any provider/model)

4) Verify it's working

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

You should see your connected models listed. 🎉 That's it — start coding, and OmniRoute auto-routes & falls back for you.

🐳 Docker

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
 -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

🛠️ From source

cp .env.example .env && npm install
PORT=20128 npm run dev

📦 pnpm

pnpm install -g omniroute && pnpm approve-builds -g && omniroute

🐧 Arch Linux (AUR)

yay -S omniroute-bin && systemctl --user enable --now omniroute.service

📖 Docker Guide — Compose profiles, Caddy HTTPS, Cloudflare tunnels.

1. kr/claude-sonnet-4.5 (Kiro — unlimited)
2. if/kimi-k2-thinking (Qoder — unlimited)
3. pol/gpt-5 (Pollinations — no key)
4. lc/longcat-flash-lite (50M tok/day backup)
Compression: aggressive (~50%) → double your free quota · Cost: 0ドル/mo

• Runtime: Node.js 20.20.2+, 22.22.2+, or 24.x LTS (24 LTS recommended)
• Language: TypeScript 5.9 — 100% TypeScript across src/ and open-sse/ (zero any in core modules since v2.0)
• Framework: Next.js 16 + React 19 + Tailwind CSS 4
• Database: better-sqlite3 (SQLite) + LowDB (JSON legacy) — domain state, proxy logs, MCP audit, routing decisions, memory, skills
• Schemas: Zod (MCP tool I/O validation, API contracts)
• Protocols: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE)
• Streaming: Server-Sent Events (SSE) + WebSocket bridge (/v1/ws)
• Auth: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization
• Testing: Node.js test runner + Vitest (4,690+ test cases across 517 files — unit, integration, E2E, security, ecosystem)
• Platforms: Desktop (Electron), Android (Termux), PWA (any browser)
• CI/CD: GitHub Actions (auto npm publish + Docker Hub on release)
• Website: omniroute.online
• Package: npmjs.com/package/omniroute
• Docker: hub.docker.com/r/diegosouzapw/omniroute
• Resilience: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing

Contributors

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 for detailed guidelines.

# Create a release — npm publish happens automatically
gh release create v3.8.2 --title "v3.8.2" --generate-notes

Special thanks to 9router by 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 by router-for-me — the original Go implementation that inspired this JavaScript port.

Special thanks to Caveman by JuliusBrussee (⭐ 51K+) — the viral "why use many token when few token do trick" project whose caveman-speak compression philosophy inspired OmniRoute's standard compression mode and 30+ filler/condensation regex rules.

Special thanks to RTK - Rust Token Killer by RTK AI — the high-performance command-output compression project whose terminal, build, test, git, and tool-output filtering model inspired OmniRoute's RTK engine, JSON filter DSL, raw-output recovery, and stacked RTK → Caveman compression pipeline.

MIT License - see LICENSE for details.