🚀 OmniRoute — The Free AI Gateway

💰 ~1.53B Free Tokens / Month

Stacking free tiers by hand is painful — dozens of SDKs, dozens of rate limits, and no idea how much you actually have. OmniRoute aggregates the documented free tiers of 43 provider pools / 516 models into one honest number and shows it live on the dashboard (/dashboard/free-tiers).

Animated summary of the live /dashboard/free-tiers page. Full methodology (pool dedupe, credit tiers, provider terms): docs/reference/FREE_TIERS.md.

_{These figures are re-audited every two weeks against the live catalog and move both ways — a provider ends a free tier and the number drops; a new one lands and it climbs. We publish what the catalog actually computes, never a rounded-up best case.}

⭐ Star the repo if OMNIROUTE helped you save money and make your work easier.

💬 Join the community

👋 Follow the maintainer — get new providers, releases & tips first:

Questions, provider tips, roadmap & support → Discord · Telegram · WhatsApp 🌍 Global / 🇧🇷 Brasil

🧩 Available

🚀 Quick Start	🎯 Combos	🌐 Providers
🔌 CLI & MCP	🗜️ Compression	🌍 Website

💥 The Promise	🤔 Why	🏆 What Sets Apart
🤖 Compatible CLIs	🖥️ Where It Runs	🔒 Private
🎬 In Action	📸 Screenshots	📧 Support

🌐 In 43 languages

🆓 Works the second you install it — no keys, no config

# Fresh install, zero credentials — `auto` already works:
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

_{Prefer a specific free backend? Call it directly, e.g. oc/… (OpenCode Free) or felo/… (Felo). Then graduate to auto and let OmniRoute pick.}

💥 The Promise

🤔 Why OmniRoute?

🤝 Supported by our Open Source Friends

Want to join as an Open Source Friend? These are the companies that back open source and help keep OmniRoute moving — and we say publicly where every token they give us goes. Reach out: diegosouza.pw@outlook.com

Kimi Moonshot AI

Thanks to Kimi (Moonshot AI), our founding Open Source Friend, for backing this project! Kimi is the AI lab behind the open-weight K2 and K3 model families — Kimi K3 delivers a 1M-token context window, native vision and frontier-level coding at a fraction of closed-model prices, and works out of the box with Claude Code, Codex and every coding tool OmniRoute serves. What Kimi's support powers: Kimi's API credits power OmniRoute's AI-validated release pipeline — the merge validation powered by Kimi K3 stage that reviews every pull request before it ships — plus day-to-day feature development. First-class Kimi support ships on both rails: the direct Kimi API (kimi-k3) and the Kimi Code coding plan (OAuth and API key). OmniRoute is also the first Brazilian open-source project in Kimi's support program. Get a Kimi API key →

_{Links tagged aff=omniroute are partner links. They fund the project at no extra cost to you.}

🎯 Combos — The Flagship

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

⚡ Zero-config — just use auto

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

Model ID	What it optimizes for
auto	🎯 Balanced default (LKGP — sticks to your last good provider)
auto/coding	🧑‍💻 Quality-first weights for code generation
auto/fast	⚡ Lowest latency first
auto/cheap	💰 Cheapest per token first
auto/offline	🔋 Most quota / rate-limit headroom first
auto/smart	🔭 Quality-first + 10% exploration to discover better models

🔀 Or build your own — 19 routing strategies

All 19 strategies — mix & match per combo step:

#	Strategy	What it does
1	priority	First-target ordered list — drain each before the next 🥇
2	fill-first	Fill each target's quota fully before moving on
3	weighted	Weighted random by per-target weight
4	round-robin	Cycle through targets in order
5	p2c	Power-of-two-choices random load balancing
6	least-used	Pick the target with the lowest current load
7	random	Uniform random pick (deduplicated)
8	strict-random	Random without de-duplicating repeats 🎲
9	cost-optimized	Minimize $ per request from live catalog pricing 💸
10	headroom	Pick the target with the most remaining quota
11	reset-window	Prefer the target whose quota window resets soonest
12	reset-aware	Rank by quota reset time — short windows first 📊
13	context-relay	Hand off context across targets for long conversations 🧠
14	context-optimized	Pick the best fit for the current context size
15	cache-optimized	Pin each reusable prompt prefix to the same account — maximize prompt-cache hits 🎯
16	lkgp	Last-Known-Good Path — sticky to the last successful target
17	auto	12-factor live scoring across every connection 🤖
18	fusion	Fan out to a panel of models + a judge synthesizes one answer 🧬
19	pipeline	Chain steps — each target's output feeds the next one 🔗

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

🧱 Resilience is built in (3 independent layers)

_{📖 Auto-Combo Engine · Resilience Guide}

🏆 What Sets OmniRoute Apart

_{📊 Full methodology & per-feature detail vs 9router, OpenRouter, CLIProxyAPI & LiteLLM → docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md}

❤️ Support

OmniRoute is free and open source, built and maintained in the open. If it saves you time or money, consider supporting development:

• ⭐ Star the repo — it genuinely helps visibility
• 💖 GitHub Sponsors — fund ongoing maintenance and new providers
• 🐛 Report bugs and share feedback in Discussions

✨ What's New

Recent highlights from v3.8.20 → v3.8.49. Full history in CHANGELOG.md.

• 🗜️ Compression hardening — default-on inflation guard, Caveman packs for DE / FR / JA + Chinese (wényán), RTK filters for Gradle & .NET. → Compression
• 💸 Honest flat-rate cost — subscription / coding-plan providers read $0 in cost analytics; budget, quota & routing keep estimating. → API Reference
• ⚖️ Quota-Share routing — split a shared account's quota fairly across pooled keys, work-conserving so idle slices are lent out. → Resilience Guide
• 🤖 One-command CLI/agent setup — setup-* configures 12+ coding tools; omniroute launch / launch-codex are zero-config. → CLI Integrations
• 🛰️ Remote mode — drive a remote OmniRoute with scoped tokens (connect / contexts / tokens) + an antigravity OAuth helper for VPS installs. → Remote Mode
• 🧭 Smarter auto-routing — auto/<category>:<tier> combos, Fusion (model panel + judge), task-aware routing, per-request model / mode / USD-budget overrides. → Auto-Combo
• 🗜️ Pluggable compression — 12 composable engines + Compression Studios: LLMLingua-2, two-tier Ultra, omniglyph, per-step fidelity gate, GCF v3.2, drag-reorder editor. → Compression
• 🕵️ Transparent MITM decrypt (TPROXY) — capture CLIs that ignore proxy env vars, with a per-SNI CA + trust-store installer. → MITM/TPROXY
• 💸 Cost telemetry everywhere — X-OmniRoute-* cost/usage headers on every endpoint, cache-HIT savings header, per-key USD spend quotas. → API Reference
• 🧠 Memory you control — off by default, opt-in int8 vector quantization + typed decay, per-request x-omniroute-no-memory. → Memory
• 🛡️ Security — prompt-injection guard on every LLM route (red-team suite) + free DuckDuckGo last-resort web search. → Guardrails
• 🖼️ New endpoints — /v1/ocr (Mistral OCR) and /v1/audio/translations (Whisper-style) round out the media surface. → API Reference
• 🎨 Image / video / audio generation — one API for media: xAI Grok Imagine & Novita AI video, ComfyUI, Freepik, Adobe Firefly, Microsoft Designer, Google Imagen, Segmind, EdgeTTS. → API Reference
• 🌍 Deployment & ops — reverse-proxy basePath, browser-language auto-detect, per-key device tracking, root-less MITM trust, zh-TW localization. → Environment
• 🤝 More providers & agents — Cursor Cloud Agent, Grok Build (xAI), Ollama first-class card, Claude Sonnet 5, Zed, Requesty, SenseNova, Yuanbao, Agnes AI… and a refreshed 290-provider catalog. → Providers
• ⚡ Local performance & infra — one-click local Redis, Cloudflare Workers / Deno Deploy relay deployers, Bifrost & Mux as supervised embedded services. → Embedded Services

🤖 Compatible CLIs & Coding Agents

One config — http://localhost:20128/v1 — and every AI IDE or CLI runs on free & low-cost models.

Claude Code	Codex CLI	Cline	Kilo Code	Roo Code	Continue
Aider	ForgeCode	jcode	DeepSeek TUI	CodeWhale	OpenCode
Factory Droid	Copilot CLI	Cursor CLI	Smelt	Pi	Grok Build
Hermes Agent	OpenClaw	Goose	Open Interpreter	Warp AI	Agent Deck

＋ also works with · Kiro · Command Code · Antigravity · Windsurf · AMP · any OpenAI-compatible tool

_{📖 Per-tool setup for all 33 tools (25 CLI Code's + 8 CLI Agents) → docs/reference/CLI-TOOLS.md · 🧩 OpenCode plugin → @omniroute/opencode-provider}

🌐 290 AI Providers — 90+ Free

The most complete catalog of any open-source router: 290 providers, 90+ with a free tier, 40+ free forever.

🏢 Every major lab — through one endpoint

OpenAI	Anthropic	Gemini	xAI Grok	DeepSeek	Mistral
Qwen	Meta Llama	Groq	NVIDIA	MiniMax	Cohere
Perplexity	HuggingFace	Together	Fireworks	Cloudflare	Baidu

_{…and 220+ more — every icon resolves live from the dashboard's provider catalog. 📖 Provider Reference}

🆓 Free Forever — $0, no card

OpenCode Zen DeepSeek V4, Nemotron 3 No token cap	Kilo Code Auto-router, Tencent Hy3 Free forever	Requesty GPT-OSS 120B, Nemotron Free forever	SiliconFlow DeepSeek V3.2 / R1 Free tier	Z.AI GLM GLM-4.7 / 4.5-Flash Free forever	Baidu ERNIE ERNIE 4.0 Free forever
Qoder AI Qwen3-Max, Kimi-K2 Unlimited FREE	Pollinations GPT, Llama, Claude No key needed	Cloudflare AI 50+ models 10K neurons/day	NVIDIA NIM GLM, MiniMax ~40 RPM free	Cerebras GLM 4.7, GPT-OSS 1M tokens/day	OpenRouter :free models +$10 → higher RPM

📖 Full machine-readable catalog → docs/reference/PROVIDER_REFERENCE.md

🖥️ Where OmniRoute Runs — Anywhere

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

Platform	Install	Highlights
📦 npm (global)	npm install -g omniroute	One command, any OS
🐳 Docker	docker run … diegosouzapw/omniroute	Multi-arch AMD64 + ARM64
🖥️ Desktop (Electron)	npm run electron:build	Native window + system tray — Windows / macOS / Linux
💪 ARM	native arm64	Raspberry Pi, ARM servers, Apple Silicon
📱 Android (Termux)	pkg install nodejs && npx -y omniroute	Runs on your phone, 24/7, no root
📲 PWA	"Add to Home Screen"	Fullscreen, offline, installable from browser
🧩 OpenCode plugin	@omniroute/opencode-provider	Native OpenCode integration
🛠️ From source	npm install && npm run dev	Hack on it, contribute

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

🔒 Private & Local-First

_{📖 Authorization · Guardrails · Compliance}

🔌 Full CLI + A2A & MCP

Beyond the server, OmniRoute is a full command-line cockpit with 80+ commands, plus open agent protocols so an AI agent can drive it on its own.

⌨️ A real CLI (not just start)

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

🛰️ Remote mode — run the CLI here, OmniRoute on a VPS

OmniRoute on a server? Drive it from your laptop with the same CLI. Log in once with a scoped access token; every command then targets the remote.

omniroute connect 192.168.0.15            # password → scoped token, saved as a context
omniroute models list                     # ← runs against the REMOTE server
omniroute configure codex                 # ← picks a remote model, writes a local Codex profile
omniroute tokens create --name ci --scope read   # mint narrower tokens for other machines
omniroute contexts use default            # ← switch back to the local server

Tokens are scoped read / write / admin; process-spawning routes stay loopback-only. _{📖 Remote Mode}

🤝 Connect an agent — and it controls OmniRoute itself

Expose OmniRoute over MCP, A2A, a REST API, webhooks or a remote CLI — any capable agent (or your own code) gets the keys to the whole gateway: routing, providers, combos, cache, compression, memory — autonomously. HTTP endpoints below are served under http://localhost:20128.

Interface	Endpoint / command	Use it for
🧰 MCP (stdio)	omniroute --mcp	Plug into Claude Desktop, Cursor, any MCP client
🌊 MCP (HTTP)	/api/mcp/stream	Remote MCP — 104 tools, 31 scopes, full audit trail
📡 MCP (SSE)	/api/mcp/sse	Streaming MCP transport
🤝 A2A	/.well-known/agent.json	Agent-to-agent, JSON-RPC 2.0 + SSE, 6 skills
🌐 REST API	/v1/*	OpenAI-compatible — chat, embeddings, images, audio, OCR
🔔 Webhooks	/api/webhooks	Push events (usage, quota, errors, routing) to your URL
🛰️ Remote CLI	omniroute connect	Drive a remote instance with scoped access tokens

# 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}

🗜️ Save 15–95% Tokens — Automatically

📖 How it works — pipeline, architecture & savings math

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.

Why use many tokens when few tokens do the trick? Every request passes through OmniRoute's compression pipeline transparently — no client changes. It's now a stack of 12 composable engines that run in order and mix & match per routing combo — building on ideas from RTK, Caveman (⭐ 90K+), LLMLingua-2, and Troglodita (PT-BR).

🧱 The 12-engine stack

Engines run in pipeline order; each is independently toggleable and configurable per combo:

#	Engine	What it does
1	Session-Dedup	Drops content repeated across turns (content-addressed, cross-turn)
2	CCR	Archives large blocks behind retrieve markers, fetched on demand
3	Lite	Whitespace + image-URL trimming (latency-light baseline)
4	RTK	Smart tool-result filtering, dedup & truncation (command-aware)
5	Responses Tool Output	Lossless-first JSON + bounded diagnostic compression for shell/patch/search/build outputs (Responses API)
6	Headroom	Lossless tabular compaction of JSON arrays (~30%) via a vendored GCF codec
7	Relevance	Extractive sentence scoring against the last user query
8	Caveman	Rule-based prose compression (~65–75% on output)
9	Aggressive	Summarization + progressive aging of old turns
10	LLMLingua-2	ML semantic pruning via MobileBERT ONNX — code-safe, async
11	Ultra	Heuristic token pruning with an optional small-model (SLM) tier
12	OmniGlyph	Experimental context-as-image encoding routed to Claude Fable 5 (most aggressive; opt-in)

Code blocks, URLs and structured data are always preserved byte-perfect. One-click presets combine the engines:

Mode	Savings	Best for
🪶 Lite	~15%	Always-on safe default
🪨 Standard (Caveman)	~30%	Daily coding
⚡ Aggressive	~50%	Long tool-heavy sessions
🔥 Ultra	~75%	Maximum savings
🧰 RTK	60–90%	Shell/test/build/git output
🔗 Stacked (RTK → Caveman)	78–95%	Mixed prompts + tool logs

Real example — Standard mode:

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

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

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

PT-BR example — Troglodita mode:

Antes (42 tokens): "O problema é que o componente está re-renderizando porque uma nova referência de objeto está sendo criada em cada ciclo de renderização. Eu recomendaria usar useMemo."

Depois (12 tokens): "Re-render: ref nova cada ciclo (objeto inline recriado). Usar useMemo."

Mesma resposta. ~70% menos tokens. Precisão técnica intacta. ✅

🎚️ Beyond the engines — output styles, the adaptive dial & per-request control

The 12 engines above shrink what goes in. Three more layers shape how, when, and what comes out:

• 🪄 Output Styles (output-axis steering) — inject deterministic, cache-safe response-shaping instructions; combinable, each at lite / full / ultra intensity. Adding a style is a one-line registry entry:
  • Terse prose — drop filler / articles / hedging; keep technical substance exact.
  • Less code — "lazy senior dev" YAGNI: smallest working change, no unrequested scaffolding.
  • Terse CJK (文言) — classical-Chinese ultra-terse style (locale-gated to zh).
• 🎯 Adaptive context-budget (the dial) — instead of one on/off token threshold, escalate the cheapest, most-lossless engines only as far as needed to fit the model's context window. Policy: reserve-output (default, model-aware) · percentage · absolute. Mode: floor (guarantee fit) · replace-autotrigger (your explicit choice wins) · off (legacy threshold).
• 🎛️ Where compression is decided (precedence, high → low) — per-request x-omniroute-compression header › routing-combo override › active named profile › adaptive / auto-trigger › panel default › off. The applied plan echoes back in the X-OmniRoute-Compression: <mode>; source=<source> response header.

Auto-trigger by token threshold, flip on the adaptive dial, pin a named profile, set a one-off per request, or assign a pipeline per routing combo — whichever fits the workload. An opt-in offline eval harness (npm run eval:compression) scores fidelity vs. savings on a pinned corpus before you promote a change.

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

⚡ Quick Start

1) Install & run

npm install -g omniroute
omniroute

💡 See npm warn ERESOLVE or peer-dep warnings? They're harmless.

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, ~50 credits/month per account) 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.

If your client cannot send custom headers, OmniRoute also exposes tokenized compatibility aliases:

OpenAI catalog:   http://localhost:20128/vscode/YOUR_KEY/
OpenAI models:    http://localhost:20128/vscode/YOUR_KEY/models
OpenAI chat:      http://localhost:20128/vscode/YOUR_KEY/chat/completions
OpenAI responses: http://localhost:20128/vscode/YOUR_KEY/responses
Ollama chat:      http://localhost:20128/vscode/YOUR_KEY/api/chat
Ollama tags:      http://localhost:20128/vscode/YOUR_KEY/api/tags

Use these only for clients that cannot attach Authorization: Bearer .... Header auth remains the preferred mode.

📦 More install methods — Docker, source, pnpm, Arch

🐳 Docker

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1: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 add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute

🐧 Arch Linux (AUR)

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

🔧 Nix (Flake)

# Using Nix flakes
nix develop
npm run dev

# Or using devbox
devbox run npm run dev

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

🦭 Podman

# 1. Build the image
podman build --target runner-base -t omniroute:base .

# 2. Fix data directory permissions for rootless Podman
mkdir -p data && podman unshare chown 1000:1000 ./data

# 3. Set runtime in .env, then run (see contrib/podman/ for Quadlet)
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d

📖 Podman Guide — Quadlet setup, podman-compose, Quadlet.

⚡ Faster / leaner install (skip the native build)

The native SQLite engine (better-sqlite3) is an optional dependency, so a global install never blocks on compiling from source: it uses a prebuilt binary when one matches your platform/Node, and otherwise falls back transparently to a pure-JS engine (node:sqlite on Node 22+, else the bundled sql.js WASM) — no build tools required.

To skip the post-install native warm-up entirely (CI, headless, or slow machines):

OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute   # CI=1 also skips it

For the fastest installs prefer pnpm (content-addressed store + hard links — see above). For a dashboard-free, headless runtime use the Docker base profile (above) or the Termux guide. The CLI and the web dashboard are served by the same process on one port, so there is no separate CLI-only package today.

🎬 OmniRoute in Action

🇧🇷 Português Guia completo

🇺🇸 English Complete walkthrough

🇷🇺 Русский Полное руководство

🎬 Made a video about OmniRoute? Open an issue or discussion with the link — we'll feature it here.

📧 Support & Community

Everything in one place — follow the maintainer, chat with the community, or open an issue.

Channel	Where / how
💼 LinkedIn — follow the maintainer	linkedin.com/in/diegosouzapw
🐙 GitHub — follow for releases & tips	@diegosouzapw
💬 Discord	discord.gg/U47eFqAXCn
✈️ Telegram	t.me/omnirouteOficial
🟢 WhatsApp — 🌍 Global	join the group
🟢 WhatsApp — 🇧🇷 Brasil	entrar no grupo
🌍 Website	omniroute.online
📦 Source code	github.com/diegosouzapw/OmniRoute
🐛 Report a bug	open an issue — attach npm run system-info output
🤝 Contribute	CONTRIBUTING.md · Branching & Release Model · pick a good first issue
⭐ Support the project	Star the repo · GitHub Sponsors

---

🛠️ Tech Stack

Layer	Technology
Runtime	Node.js 22.x / 24.x LTS — >=22.22.2 <23 || >=24.0.0 <27
Language	TypeScript 6.0 — 100% TypeScript across src/ and open-sse/ (zero any in core since v2.0)
Framework	Next.js 16 + React 19 + Tailwind CSS 4
Database	better-sqlite3 (SQLite, WAL journaling) + LowDB (JSON legacy) — 95 domain modules, 110 migrations
Memory	SQLite FTS5 full-text + int8-quantized vector embeddings, typed decay
Schemas	Zod 4 — MCP tool I/O validation + API contracts
Protocols	MCP (stdio / HTTP / SSE) + A2A v0.3 (JSON-RPC 2.0 + SSE)
Streaming	Server-Sent Events (SSE) + WebSocket bridge (/v1/ws)
Compression	12-engine pipeline — RTK, Caveman, LLMLingua-2 (MobileBERT ONNX), GCF, OmniGlyph
Auth & security	OAuth 2.0 (PKCE) + JWT + API Keys + MCP scoped auth · AES-256-GCM at rest · DOMPurify
Stealth	wreq-js — JA3 / JA4 TLS fingerprint impersonation, 3-level proxy
Resilience	Circuit breaker, exponential backoff, anti-thundering-herd, auto-combo self-healing
Logging	pino — structured JSON logs with request context
Testing	Node.js test runner + Vitest — 25,000+ test cases across 3,300+ 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
Links	Website · npm · Docker Hub

📖 Documentation

📘 Getting Started

Document	Description
User Guide	Providers, combos, CLI integration, deployment
Setup Guide	Full install methods, CLI tool configs, protocol setup, timeout tuning
CLI Tools Guide	Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot
Remote Mode	Drive a remote OmniRoute (VPS) from your laptop CLI via scoped access tokens
Claude Code Config	Point Claude Code at OmniRoute (local/remote) with launch + per-model profiles
Quick Start	3-step install → connect → configure

🔧 Operations & Deployment

Document	Description
Docker Guide	Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags
Podman Guide	Quadlet systemd integration, podman-compose, SELinux
VM Deployment	Complete guide: VM + nginx + Cloudflare setup
Fly.io Deployment	Deploy to Fly.io with persistent storage
Termux Guide	Run OmniRoute on Android via Termux
PWA Guide	Progressive Web App install, caching, architecture
Uninstall Guide	Clean removal for all install methods
Environment Config	Complete .env variables and references

🧠 Features & Architecture

Document	Description
Architecture	System architecture, data flow, and internals
Compression Guide	7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked
RTK Compression	Command-output compression, filters, trust, verify, raw-output recovery
Compression Engines	Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces
Compression Rules Format	JSON rule-pack schemas for Caveman and RTK filters
Compression Language Packs	Language detection and Caveman rule-pack authoring
Resilience Guide	Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing
Auto-Combo Engine	12-factor scoring, mode packs, self-healing
Proxy Guide	3-level proxy system, 1proxy marketplace, registry CRUD
Free Tiers	25+ free API providers consolidated directory
Features Gallery	Visual dashboard tour with screenshots
Codebase Documentation	Beginner-friendly codebase walkthrough

🤖 Protocols & APIs

Document	Description
API Reference	All endpoints with examples
OpenAPI Spec	OpenAPI 3.0 specification
MCP Server	104 MCP tools, IDE configs, Python/TS/Go clients
MCP Server Guide	MCP installation, transports, and tool reference
A2A Server	JSON-RPC 2.0 protocol, skills, streaming, task mgmt
A2A Server Guide	A2A agent card, tasks, skills, and streaming

📋 Project & Quality

Document	Description
Contributing	Development setup and guidelines
Branching & Release Model	Where PRs target (release/*), what main and tags mean
Changelog	Full per-version release history
Security Policy	Vulnerability reporting and security practices
i18n Guide	40+ language support, translation workflow, RTL
Release Checklist	Pre-release validation steps
Coverage Plan	Test coverage strategy and 25,000+ test suite

⭐ Top Contributors

OmniRoute is shaped by a passionate open-source community. These individuals have made exceptional contributions that directly impact the quality, stability, and reach of the project. Thank you.

oyi77 🥇 213 commits • +114K lines Analytics engine, SQL aggregations, proxy marketplace, test coverage	R.D. & Randi 🥈 108 commits • +38K lines Endpoints page, tunnel integrations, Docker workflows, A2A status, compression UI	Chris Staley 🥉 70 commits • +1.8K lines SSE stream hardening, Responses API, Gemini pagination, test regression fixes	zenobit 🏅 62 commits • +22K lines CI/CD pipeline, i18n for 33 languages, Void Linux package, platform fixes	Jan Leon 🏅 58 commits • +22K lines Reasoning-effort routing, proxy controls, quota visibility, Live Zone compression
backryun 🏅 53 commits • +70K lines Provider catalog curation — Perplexity, Kimi, Cerebras, Copilot, LMArena refreshes	Chirag Singhal 🏅 46 commits • +4.8K lines Error sanitization, MITM prefill fix, fusion judge, breaker/429 correctness	kfiramar 🏅 38 commits • +1.7K lines Codex websocket + passthrough, auth/onboarding, Electron hardening, DB migrations	Benson K B 🏅 28 commits • +9.2K lines Electron desktop app, auto-updater, release build workflows, cross-platform CI	Hernan J. Ardila 🏅 25 commits • +174K lines Zero-latency combos, vision-bridge auto-routing, catalog context-length, resilience 429 hints

🙏 These contributors' features, bug fixes, and infrastructure improvements are a core part of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.

---

💖 Sponsors

A heartfelt thank-you to the people who fund OmniRoute out of their own pocket — every contribution keeps the project free, independent and moving.

Prof. Igor Morais 💛 Sponsor

longtao 💛 Sponsor

_{… and others who prefer to stay private 💛}

💖 Become a sponsor → — every dollar keeps OmniRoute free and independent.

👥 500+ Contributors

How to Contribute

1. Fork the repository
2. Branch from the active release/vX.Y.Z tip (not main) — see Branching & Release Model
3. Create your feature branch (git checkout -b feat/amazing-feature)
4. Commit your changes (git commit -m 'feat: add amazing feature')
5. Push to the branch (git push origin feat/amazing-feature)
6. Open a Pull Request with base = that release/vX.Y.Z branch

See CONTRIBUTING.md for detailed guidelines.

Releasing a New Version

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

📊 Stars

🌍 StarMapper

🙏 Acknowledgments

OmniRoute stands on the shoulders of giants. It started as a fork of 9router and a TypeScript port of the Go project CLIProxyAPI — and from there, every subsystem below was inspired by an open-source project that got there first. Each one shaped a concrete piece of OmniRoute. This is our thank-you to all of them. 🙏

⭐ star counts as of July 2026 — go give these projects a star.

🧬 Lineage & gateway

Project	⭐	How it inspired OmniRoute
9router	22.7k	The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite.
CLIProxyAPI	43.6k	The Go implementation that inspired this JavaScript / TypeScript port.
LiteLLM	54.0k	The AI gateway whose public pricing dataset feeds our cost-tracking sync and whose provider-normalization model informed our routing.

🗜️ Context & token compression — engines

Project	⭐	How it inspired OmniRoute
Caveman	90.8k	The viral "why use many token when few token do trick" project — its caveman-speak philosophy powers our standard compression mode and 30+ filler/condensation rules.
RTK – Rust Token Killer	71.8k	High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline.
headroom	60.1k	Reversible context-compression (SmartCrusher) — inspired our headroom engine and the ccr retrieve-marker pattern.
LLMLingua	6.5k	Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open llmlingua engine.
llmlingua-2-js	30	The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine.
Troglodita	26	PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar.
ponytail	86.0k	The viral "lazy senior dev" YAGNI-coder skill — inspired our less-code Output Style: smallest-working-change steering that cuts _generated_ code (the output-axis sibling to Caveman's terse prose).

🧩 Compact formats, token research & code-aware tooling

Project	⭐	How it inspired OmniRoute
TOON	24.9k	Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage.
GCF – Graph Compact Format	22	First inspired our tabular compaction stage; now its zero-dependency, lossless generic-profile encoder is vendored directly as the Headroom codec (MIT, SPDX-marked), current with GCF spec v3.2.
token-optimizer-mcp	444	Brotli/SQLite cache + per-session context-delta — inspired our session-dedup engine.
token-savior	1.1k	Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction.
token-saver	117	Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip.
token-optimizer	1.7k	"Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking.
TokenMizer	16	A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design.
OmniCompress	3	Rust columnar-JSON + content-addressed retrieve + cross-message dedup — validated our headroom/ccr/session-dedup engine design and the cache-stable "compressed form is position-independent" invariant.
mcp-compressor	98	MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction.
RepoMapper	187	Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration.
quiet-shell-mcp	4	Declarative shell-output reduction over MCP — validated our declarative bash-output compaction.
ts-morph	6.1k	TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals.

🧠 Memory & RAG

Project	⭐	How it inspired OmniRoute
Mem0	61.2k	Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture.
Letta (MemGPT)	23.9k	Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model.
WFGY	1.8k	The ProblemMap taxonomy of 16 recurring RAG/LLM failure modes — the shared vocabulary in our troubleshooting guide.

🛰️ Traffic inspection, MITM & transparent proxy

Project	⭐	How it inspired OmniRoute
llm-interceptor	49	MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT).
ProxyBridge	5.5k	Transparent per-process proxy routing — inspired our crash-safe MITM teardown, socket idle-timeouts, /proc process attribution and TPROXY capture.

📚 Model data, observability & UI

Project	⭐	How it inspired OmniRoute
models.dev	6.0k	Open database of AI model specs, pricing and capabilities — synced natively into our model catalog.
React Flow / xyflow	37.7k	The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio.
LangGraph	37.6k	LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view.
Langfuse	31.4k	Its trace → span → generation observability model shaped our Compression Studio waterfall.
Kiali	3.6k	Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio.
lobe-icons	2.2k	AI/LLM brand logos that render the provider icons across our dashboard.

🛡️ Security

Project	⭐	How it inspired OmniRoute
awesome-secure-defaults	710	A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).

🧭 Complementary tools

Project	⭐	How it inspired OmniRoute

📄 License

MIT License - see LICENSE for details.

---

⬆ Back to top · Built with ❤️ for the open-source AI community.

_{OmniRoute v3.8.49 · Node ≥22.22.2 · MIT License · omniroute.online}