Sandbox
@diegosouzapw/OmniRoute

AI gateway for Claude Code, Codex, and Cursor

OmniRoute gives agent tools one local endpoint for model access. It handles provider routing, quota-aware fallback, MCP and A2A connections, and token-saving compression so your agent can keep going when one backend is slow or limited.

64,149 stars9k forksTypeScriptUpdated 6d ago
Free AI Tools So Good They're Making Paid Versions Obsolete
Vaibhav Sisinty445k views • 1 month ago

Videos about this repo

Who it's for

Builders who run Claude Code, Codex, Cursor, Cline, or Copilot and want one endpoint for model access and fallback.

What it delivers

You can keep coding through quota changes and provider failures without reconfiguring each agent tool.

What it does

One endpoint for many providers

Routes OpenAI-compatible requests through a single local server to hundreds of providers and models.

Quota-aware fallback

Switches to another healthy provider when a key, quota, or rate limit runs out.

Token compression

Uses RTK and Caveman compression to reduce token usage on long prompts and tool output.

MCP and A2A support

Includes MCP server support and A2A integration for agent tool connections.

Works with common agent clients

Supports Claude Code, Codex, Cursor, Cline, Copilot, and other OpenAI-compatible clients.

Desktop and PWA access

Includes desktop and browser-based interfaces for managing routes, quotas, and usage.

How to get it

  1. 1Run
    # 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!"}]}'
  2. 21) Install & run
    npm install -g omniroute
    omniroute
  3. 33) 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. 44) Verify it's working
    curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"
  5. 5If your client cannot send custom headers, OmniRoute also exposes tokenized…
    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
  6. 6Docker
    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

README

OmniRoute Dashboard

🚀 OmniRoute — The Free AI Gateway

OmniRoute — Never stop coding. Every AI tool → 356 providers — 150+ free — through one endpoint. Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini with auto-fallback. RTK + Caveman stacked compression saves 15–95% tokens (~89% avg) — never hit limits. 356 AI providers · 150+ free tiers · ~1.47B free tokens/mo · 19 routing strategies · $0 to start.

💰 ~1.47B 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 catalogs 444 free-tier entries across 34 recurring pool keys and computes the token headline from the 16 pools with a published positive monthly budget plus five per-model Groq caps, deduplicated by shared pool. Quotas that only open after a regional identity check (today: ModelScope) are shown apart, +~6M behind regional identity verification, and never summed into the headline. The result stays visible on the dashboard (/dashboard/free-tiers).

OmniRoute free-tier budget card: ~1.47B free tokens per month steady, up to ~2.10B in the first month with signup credits, from 34 documented recurring pool keys covering 444 cataloged free-tier entries behind one endpoint. Honest pool-deduped math — each shared pool counted once, including 16 recurring pools with a published positive monthly token budget plus five per-model Groq caps; 13 providers are marked avoid in the terms-risk catalog so you decide. Budget bar includes Mistral 1B, Nara 210M, LLM7 150M, Groq 30M (five per-model caps) and smaller pools, plus first-month signup credits and permanently-free no-token-cap providers surfaced separately so they never inflate the headline. Live used/remaining on /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.

Stars diegosouzapw%2FOmniRoute | Trendshift Star History Rank olud.ai

💬 Join the community

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

Follow Diego on LinkedIn Follow @diegosouzapw on GitHub

Discord Telegram WhatsApp Global WhatsApp Brasil Website

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


📈 The Gateway Keeps Growing

v3.8.49v3.8.50v3.8.51+
🌐 Providers290352more queued
🧠 Unique chat model IDs11851312
🖼️ Modality Bridge🆕 vision + audio + video
📡 Radar free catalog🆕 opt-in
⚖️ Quota-aware scheduling🆕 Quota-Share
📊 Quota telemetry🆕 live

Roadmap — riding the rail to v3.9.0 LTS


🧩 Available

npm version NPM Monthly Docker Hub License: MIT Docker Pulls Electron Downloads

🚀 Start🚀 Quick Start📦 Install🆓 Zero-config
💡 Learn💥 The Promise🤔 Why OmniRoute🏆 What Sets Apart
⚙️ Features🎯 Combos🌐 Providers🔌 CLI & MCP
🗜️ Compression🖥️ Where It Runs🔒 Private
👀 See it🎬 In Action✨ What's New🤖 Compatible CLIs
💚 Support💚 Support / Donate💬 Community💖 Sponsors
📦 Project🛠️ Tech Stack📖 Docs👥 Contributors
🌐 In 51 languages

English (en) Português — Brasil (pt-BR) Português (pt) Español (es) Français (fr) Italiano (it) Deutsch (de) Nederlands (nl) Русский (ru) Українська (uk-UA) Polski (pl) Čeština (cs) Slovenčina (sk) Română (ro) Magyar (hu) Български (bg) Dansk (da) Suomi (fi) Norsk (no) Svenska (sv) 中文 — 简体 (zh-CN) 中文 — 繁體 (zh-TW) 日本語 (ja) 한국어 (ko) ไทย (th) Tiếng Việt (vi) Bahasa Indonesia (id) Bahasa Melayu (ms) Filipino (phi) हिन्दी (hi) ગુજરાતી (gu) मराठी (mr) தமிழ் (ta) తెలుగు (te) বাংলা (bn) اردو (ur) فارسی (fa) العربية (ar) עברית (he) Türkçe (tr) Azərbaycan (az) Kiswahili (sw) Ελληνικά (el) Hrvatski (hr) Српски (sr) Lietuvių (lt) Eesti (et) Latviešu (lv) Slovenščina (sl) Malti (mt) Gaeilge (ga)


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

Works the second you install it — zero config. Three steps: 1. Install — npm i -g omniroute, server boots on localhost:20128. 2. Point your tool at http://localhost:20128/v1 — any OpenAI-compatible tool (Claude Code, Cursor, Cline). 3. It answers — call model auto for an instant reply, with no API key, no signup, no configuration. Keyless provider OpenCode Free is pre-wired into the auto combo, so a fresh install responds out of the box.
# 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 oc/… (OpenCode Free) directly. Then graduate to auto and let OmniRoute pick.

📦 Copy-paste quickstart scripts for Python, Node.js, PHP, and cURLexamples/quickstart/


💥 The Promise

The Promise — One endpoint and 356 providers. Automatic fallback keeps routing while another healthy target is available. Six pillars: resilient fallback across 356 providers · up to 95% token savings on eligible workloads · $0 to start with 150+ free tiers and 52 recurring/keyless free-forever providers · 36 CLI/agent integrations through one config · OpenAI, Claude, Gemini and Responses API compatibility at /v1 · production controls including circuit breakers, TLS stealth, MCP 110 tools, A2A, memory, guardrails, evals and 39,000+ static test declarations across 5,100+ tracked test files.

🤔 Why OmniRoute?

Why OmniRoute — stop juggling 10 dashboards, dead API keys and surprise bills. Ten daily pains vs fixes: quota expiring unused → maximize subscriptions; rate limits mid-coding → 4-tier auto-fallback (Subscription → API → Cheap → Free); tool outputs burning tokens → RTK + Caveman compression (15–95%); expensive APIs → cost-optimized routing; every tool its own setup → one endpoint, one dashboard; AI blocked → 3-level proxy + TLS stealth; dead keys → 3-layer resilience (circuit breakers, key cooldown, model lockout); team sharing one subscription → key pools with fair-share quotas; prompts through someone's cloud → local-first with AES-256-GCM encrypted keys; no spend visibility → live analytics (usage, quota, savings, p95 latency).
OmniRoute request flow: your IDE or CLI (Claude Code, Cursor, Cline…) calls one local endpoint (http://localhost:20128/v1); the OmniRoute Smart Router (RTK + Caveman compression, 19 routing strategies, circuit breakers, TLS stealth, MCP, A2A, guardrails) can fall back across 4 provider tiers while an eligible healthy target remains — Tier 1 Subscription, Tier 2 API Key, Tier 3 Cheap and Tier 4 Free.

🤝 Supported by our Open Source Friends

Kimi K3 — Open Frontier Intelligence · 2.8T parameters · 1M-token context

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)Kimi (Moonshot AI)
Kimi
Moonshot AI

Founding Open Source Friend
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 with 15% extra credits →
Cheaper Inference
Cheaper Inference
cheaperinference.com

Open Source Friend
Thanks to Cheaper Inference, an OmniRoute Open Source Friend, for backing this project! Cheaper Inference is a cost-ranked gateway that resells 42 frontier models — Claude, GPT-5.x, Gemini, Kimi K3, GLM, DeepSeek, Grok and MiniMax — behind one OpenAI-compatible endpoint, routing each request to the cheapest eligible provider without ever charging above the model maker's list price.

First-class support in OmniRoute: Chat Completions, the native /v1/responses endpoint, vision, tool calling and 3 image models (grok-imagine, nano-banana-pro, nano-banana-2, reachable as cheaperinference/<model>). Get an API key →

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


🎟️ Affiliates Promo — free signup coupons from providers we don't sponsor (click to expand)

This section is for referral/coupon codes only. Sponsored partnerships live in 🤝 Supported by our Open Source Friends above. OmniRoute has no sponsorship or partnership with the providers listed here — these are public coupons anyone can use.

AgentRouter
AgentRouter
agentrouter.org
AgentRouter — affiliate signup · $100 free credits on signup (free server, expect higher latency — best for testing, not production). First-class support in OmniRoute since v3.8.50: Chat Completions, the Anthropic-compatible wire format and the OpenAI-compatible path. Available models include claude-opus-4-8, claude-opus-5, gpt-5.6-sol and more. Grab your $100 →

⚠️ Affiliate link — OmniRoute has no sponsorship or partnership with this provider.

Know another provider with a generous free signup coupon that benefits OmniRoute users? Open an issue and we'll add it here.


🎯 Combos — The Flag

Files in the repo

Repository payload95 top-level entries
  • .github
  • .husky
  • .vale
  • .vscode
  • @omniroute
  • bin
  • changelog.d
  • config
  • contrib
  • docker
  • docs
  • electron
  • examples
  • images
  • open-sse
  • packages
  • public
  • scripts
  • skills
  • src
  • tests
  • .cbmignore
  • .dockerignore
  • .editorconfig
  • .env.devin-bridge.example
  • .env.example
  • .env.homolog.example
  • .gitattributes
  • .gitignore
  • .gitleaks.toml
  • .i18n-state.json
  • .mailmap
  • .markdownlint.json
  • .mergify.yml
  • .node-version
  • .npmignore
  • .npmrc
  • .nvmrc
  • .prettierignore
  • .size-limit.json
  • .trivyignore
  • .vale.ini
  • .zizmor.yml
  • AGENTS.md
  • CHANGELOG.md
  • CLAUDE.md
  • CODE_OF_CONDUCT.md
  • codecov.yml
  • CONTRIBUTING.md
  • docker-compose.prod.yml
  • docker-compose.yml
  • Dockerfile
  • Dockerfile.bun
  • eslint.complexity-ratchets.config.mjs
  • eslint.complexity.config.mjs
  • eslint.config.mjs
  • eslint.sonarjs.config.mjs
  • flake.lock
  • flake.nix
  • fly.toml
  • GEMINI.md
  • knip.json
  • LICENSE
  • llm.txt
  • Makefile
  • news.json
  • next.config.mjs
  • package-lock.json
  • package.json
  • playwright.config.ts
  • pnpm-workspace.yaml
  • pnpm.json
  • postcss.config.mjs
  • prettier.config.mjs
  • promptfooconfig.yaml
  • README.md
  • ROADMAP.md
  • SECURITY.md
  • socket.yml
  • sonar-project.properties
  • source.config.ts
  • stryker.conf.json
  • stryker.disablebail.json
  • task-c1-report.md
  • task-c2-report.md
  • task-c3-report.md
  • THIRD_PARTY_NOTICES.md
  • tsconfig.json
  • tsconfig.typecheck-api.json
  • tsconfig.typecheck-core.json
  • tsconfig.typecheck-dashboard.json
  • tsconfig.typecheck-noimplicit-core.json
  • vitest.config.ts
  • vitest.e2e-live.config.ts
  • vitest.mcp.config.ts

Discussion (0)

Ask about usage, or say what you built with it

Sign in to join the discussion.

No comments yet. Be the first to say what this is good for.

More tools

JuliusBrussee/
caveman

🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman

105k
1 add
MemPalace/
mempalace

The best-benchmarked open-source AI memory system. And it's free.

59k
stablyai/
orca

Orca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

66k

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io

132k
headroomlabs-ai/
headroom

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

71k
virgiliojr94/
book-to-skill

Turn any technical book PDF into a Claude Code skill — ready to study, reference, and use while you work.

30k