diegosouzapw/OmniRoute

🚀 OmniRoute — The Free AI Gateway

💰 ~1.53B Free Tokens / Month

⭐ 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

🆓 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

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

🎯 Combos — The Flagship

⚡ 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:

🔀 Or build your own — 19 routing strategies

All 19 strategies — mix & match per combo step:

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

• 🗜️ 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

📖 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

🏢 Every major lab — through one endpoint

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

🆓 Free Forever — $0, no card

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

🖥️ Where OmniRoute Runs — Anywhere

📖 Docker Guide · Desktop · Termux · PWA · OpenCode

🔒 Private & Local-First

📖 Authorization · Guardrails · Compliance

🔌 Full CLI + A2A & MCP

⌨️ 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.

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

🧱 The 12-engine stack

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

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

Real example — Standard mode:

PT-BR example — Troglodita mode:

🎚️ 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

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. Prepare the bind-mounted data directory
mkdir -p data

# 2. Linux + local rootless Podman only (never a remote Podman Machine client):
podman unshare chown 1000:1000 ./data

# 3. Set the runtime hint, build the local Compose image, and start
echo "CONTAINER_HOST=podman" >> .env
podman compose --profile base up -d --build

On macOS or Windows, Podman uses a remote Podman Machine: skip podman unshare and follow the topology-specific data directory guidance.

📖 Podman Guide — Compose builds, Podman Machine, and Linux/systemd Quadlet setup.

⚡ 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

📧 Support & Community

🛠️ Tech Stack

📖 Documentation

📘 Getting Started

🔧 Operations & Deployment

🧠 Features & Architecture

🤖 Protocols & APIs

📋 Project & Quality

⭐ Top Contributors

💖 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.

… and others who prefer to stay private 💛

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

👥 500+ Contributors

How to Contribute

1. 1Fork the repository
2. 2Branch from the active release/vX.Y.Z tip (not main) — see Branching & Release Model
3. 3Create your feature branch (git checkout -b feat/amazing-feature)
4. 4Commit your changes (git commit -m 'feat: add amazing feature')
5. 5Push to the branch (git push origin feat/amazing-feature)
6. 6Open 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. 🙏

🧬 Lineage & gateway

🗜️ Context & token compression — engines

🧩 Compact formats, token research & code-aware tooling

🧠 Memory & RAG

🛰️ Traffic inspection, MITM & transparent proxy

📚 Model data, observability & UI

🛡️ Security

🧭 Complementary tools

📄 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