开源项目 GitHub Trending Weekly 2026-07-05T14:17 正文 ok 6430 words

🔥diegosouzapw/OmniRoute：每月约16亿免费Token的统一AI网关

英文标题：🔥 diegosouzapw/OmniRoute

OmniRoute 聚合 237 家提供商，每月稳定提供约 16 亿免费 token（首月可达 21 亿），让开发者通过单一端点接入 Claude、GPT、Gemini 等 500+ 模型。它支持 17 种路由策略、RTK+Caveman 堆叠压缩（节省 15-95% token）、智能自动回退、额度共享和 MCP/A2A 协议，并兼容 24+ 编码代理。对开发者而言，无需管理多套 SDK 和速率限制即可零成本开始，且通过多层弹性设计保证零停机。

打开原文相关 11 · 机会 3

237.3 KB

2.7 KB

5.1 KB

中文

💰 每月约 16 亿免费 Token

手动叠加免费额度非常痛苦——数十个 SDK、诸多速率限制、完全不知道实际可用额度。OmniRoute 将 40 多个提供商池 / 500 多个模型 有据可查的免费额度聚合为一个诚实的数字，并实时显示在仪表板上（/dashboard/free-tiers）。

每月约 16 亿免费 token（稳定）——新用户注册赠送额度后首月可达约 21 亿。
按池去重、诚实——每个共享免费池仅计一次，因此标题数字不会像那些数十亿的竞争对手宣称那样因速率限制上限而被夸大。（若按每小时速率限制全天候计算，数字约为 100 亿；我们不公布那个数字。）
外加无法计量的部分——永久免费、无 token 上限的提供商（SiliconFlow、Z.AI GLM-Flash、Kilo、OpenCode Zen……）以及一次 $10 的 OpenRouter 充值可解锁每月额外 2400 万 token，这两项均单独呈现，绝不会虚增标题数字。
逐模型明细、当月已用/剩余实时信息，以及每个提供商透明的使用条款标记。

预览样机——待 /dashboard/free-tiers 页面验证后会替换为真实截图。完整方法（池去重、赠送额度层级、提供商条款）：docs/reference/FREE_TIERS.md。

一个端点。237 家提供商。 永不停歇地构建——让 OmniRoute 为您挑选最便宜且可用的那一个。

🚫 永不触达限制
在 237 家提供商之间以毫秒级自动回退。额度耗尽？下一个提供商无缝接管——零停机。 | 💸 节省高达 95% token
RTK + Caveman 堆叠压缩削减 15–95% 的可压缩 token（在工具密集型会话中平均约 89%）。 | 🆓 零成本起步
90+ 家提供免费额度的提供商，11 家永久免费（Kiro、Qoder、Pollinations、LongCat……）。无需信用卡。
---|---|---
🔌 所有工具开箱即用
24+ 个编码代理——Claude Code、Codex、Cursor、Cline、Copilot、Antigravity——只需一份配置。 | 🧩 单一端点
OpenAI ↔ Claude ↔ Gemini ↔ Responses API 转换。将任意工具指向 /v1 即可正常工作。 | 🛡️ 生产级
断路器、TLS 指纹隐身、MCP（95 工具）、A2A、记忆、护栏、评测。21,000+ 项测试。

别再在 10 个仪表板、失效的 API 密钥和意外账单之间手忙脚乱了。

❌ 日常痛点	✅ OmniRoute 如何解决
📉 每月订阅额度未使用就过期	最大化订阅利用率——跟踪额度，在重置前用完每个 token
🛑 编写代码时被速率限制中断	4 层自动回退——订阅 → API → 廉价 → 免费，毫秒级切换
🔥 工具输出（`git diff`、`grep`、日志）吞噬 token	RTK + Caveman 压缩——每次请求节省 15–95% 可压缩 token
💸 昂贵的 API（每提供商 $20–50/月）	成本优化路由——自动路由至最便宜的可行模型
🧰 每个 AI 工具都要单独配置	一个端点、所有工具、一个仪表板
🌍 AI 在您所在国家被屏蔽	3 层代理 + TLS 指纹隐身——在任何地方使用 AI

┌──────────────────────────────────────────────────────────┐
│        Your IDE / CLI  (Claude Code, Cursor, Cline…)       │
└─────────────────────────┬──────────────────────────────────┘
                          │ http://localhost:20128/v1
                          ▼
┌──────────────────────────────────────────────────────────┐
│                  OmniRoute — Smart Router                  │
│  RTK + Caveman compression · 17 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

组合（combo） 是 OmniRoute 自动跨模型路由的模型链。额度用尽、提供商故障或成本飙升——组合会静默地滑向下一个模型。这就是 OmniRoute 坚不可摧的原因。 🛡️

⚡ 零配置——只需使用 `auto`

无需创建组合。将模型设为 auto（或其变体），OmniRoute 就会根据您已连接的提供商实时评分构建虚拟组合：

模型 ID	优化目标
`auto`	🎯 均衡默认（LKGP——绑定至您上次成功的提供商）
`auto/coding`	🧑‍💻 面向代码生成的质量优先权重
`auto/fast`	⚡ 最低延迟优先
`auto/cheap`	💰 每 token 最低成本优先
`auto/offline`	🔋 最大额度/速率限制余量优先
`auto/smart`	🔭 质量优先 + 10% 探索以发现更优模型

🔀 或者构建您自己的——17 种路由策略

全部 17 种策略——可按组合步骤混搭：

| 策略 | 作用

---|---|---
1 | priority | 优先目标有序列表——依次耗尽 🥇
2 | fill-first | 先完全填满每个目标的额度再移动
3 | weighted | 按每目标权重加权随机
4 | round-robin | 按顺序轮转目标
5 | p2c | 二次幂双选随机负载均衡
6 | least-used | 选择当前负载最低的目标
7 | random | 均匀随机选择（去重）
8 | strict-random | 随机选择且不去重重复项 🎲
9 | cost-optimized | 根据实时目录定价最小化每次请求成本 💸
10 | headroom | 选择剩余额度最多的目标
11 | reset-window | 优先选择额度窗口最早重置的目标
12 | reset-aware | 按额度重置时间排名——短窗口优先 📊
13 | context-relay | 跨目标交接上下文以支持长对话 🧠
14 | context-optimized | 为当前上下文大小选择最佳适配
15 | lkgp | 最后已知良好路径——粘滞至上次成功的目标
16 | auto | 对每个连接进行 9 因子实时评分 🤖
17 | fusion | 将请求扇出至模型面板，由裁判合成统一答案 🧬

自动组合引擎根据 9 项因子（健康度、额度、成本、延迟、成功率、新鲜度……）对每个候选项评分——详见 docs/routing/AUTO-COMBO.md。

⚖️ 额度共享——在团队中分配一份订阅 ✨ 新功能

有多个密钥使用同一个上游账户（一个 Codex Pro 计划、一个 Kimi 密钥、一个 GLM Coding 席位）？一个密钥上的突发请求可能耗尽整个 5 小时或每小时额度，导致其他人被锁定。额度共享能公平地将提供商基于时间的额度分配给池中的密钥——而且是工作守恒的，空闲成员的份额会被借出而非浪费。

调控项	控制内容
⚖️ 分配权重	每个密钥在池中的份额——例如 `50 / 30 / 20`
📐 维度	跟踪 `%` · 请求数 · token 数 · `$`，按 5 小时 / 7 天 / 每模型窗口
🚦 策略	`hard`（超出份额即阻止）· `soft`（降级）· `burst`（使用空闲余量）
🧱 上限	每个密钥的绝对上限，独立于模式

Pool "team-codex"   ·   1 Codex Pro account   ·   3 keys   ·   5-hour window
  ├─ alice    weight 50  ██████████░░░░░░░░░░   ≤ 50% of the shared 5h quota
  ├─ bob      weight 30  ██████░░░░░░░░░░░░░░   ≤ 30%
  └─ ci-bot   weight 20  ████░░░░░░░░░░░░░░░░   ≤ 20%
Generous mode (<50% pool used) → idle shares are lent out
Strict mode  (≥50% pool used)  → each key held to its fair share

在请求离开 OmniRoute 之前于热路径中强制执行，包含每个（密钥、模型）上限 + 会话粘滞以确保提示缓存完整性。📖 额度共享引擎

🧱 弹性内建（3 个独立层级）

层级	范围	作用
🔌 断路器	整个提供商	停止对上游故障提供商的持续请求；自动探测恢复
💤 连接冷却	单个账户/密钥	跳过被限流的密钥，其他密钥继续服务
🎯 模型封锁	提供商 + 模型	仅隔离某个超出额度的模型，不影响整个连接

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

📖 自动组合引擎 · 弹性指南

🏆 OmniRoute 的独特之处

特性	OmniRoute	其他路由
🌐 提供商	237	20–100
🆓 免费提供商	90+（11 家永久免费）	1–5
🔀 路由策略	17（优先级、加权、成本优化、上下文接力、融合……）	1–3
🗜️ Token 压缩	RTK + Caveman 堆叠（15–95%）	无 / 20–40%
🧰 内置 MCP 服务器	95 工具、3 传输、30 作用域	罕见
🤝 A2A 代理协议	6 技能、JSON-RPC 2.0	无
🧠 记忆（FTS5 + 向量）	是	罕见
🛡️ 护栏（PII、注入、视觉）	是	罕见
☁️ 云代理	Codex、Cursor、Devin、Jules	无
🥷 TLS 指纹隐身	基于 wreq-js 的 JA3/JA4	无
🖥️ 多平台	Web · 桌面 · Termux · PWA	仅 Web
🌍 国际化	42 种语言	0–4

📊 与 LiteLLM、OpenRouter 及 Portkey 的详细对比 → docs/comparison/OMNIROUTE_VS_ALTERNATIVES.md

近期亮点来自 v3.8.20 → v3.8.44。完整历史见 CHANGELOG.md。

🗜️ 压缩加固——一项默认开启的膨胀保护（当压缩反而会增大提示时丢弃堆叠结果并发送原始文本），完成了适用于德语/法语/日语的Caveman 规则包（去重 + 极致）以及新的中文（文言）输入包，并具备中日自动检测功能，同时新增了面向 Gradle 和 .NET (dotnet) 构建输出的 RTK 过滤器。 → 压缩
💸 诚实的统一费率成本——订阅/编程计划提供商（ChatGPT Web、grok-web、Minimax/Kimi/GLM/阿里 Coding 计划、小米 MiMo……）如今在成本分析中显示为 $0，而非虚高的每 token 估算值，同时预算/额度/路由估算保持不变。 → API 参考
⚖️ 额度共享路由——一种专属组合策略，通过可用额度在账户间分配负载：Deficit-Round-Robin 调度、每个连接设置 max_concurrent 及冷却等待队列、多窗口用量桶（5 小时/7 天/每模型）、每个（密钥、模型）上限、会话粘滞以保证提示缓存完整性，以及来自上游 token 用量头的主动饱和。 → 弹性指南
🤖 单命令 CLI/代理设置——专属的 setup-* 命令可为每个编码工具配置通过 OmniRoute 路由（Claude Code、Codex、Cline、Continue、Cursor、Roo Code、Kilo Code、Crush、Goose、Qwen Code、Aider、OpenCode）；omniroute launch / omniroute launch-codex 为零配置启动器。 → CLI 集成
🛰️ 远程模式——通过带作用域的访问令牌从任意机器驱动远程 OmniRoute（omniroute connect / omniroute contexts / omniroute tokens），外加一个 omniroute login antigravity 助手，可在您自己的机器上运行 Google“原生/桌面”OAuth 并将凭据片段粘贴到远程/VPS 安装中（那里无法进行环回重定向）。 → 远程模式
🧭 更智能的自动路由——OpenRouter 风格 auto/<category>:<tier> 组合（例如 auto/coding:fast、auto/reasoning:pro），融合（Fusion）策略（并行扇出至模型面板，再由裁判合成答案），任务感知路由（按任务类型选择最佳连接），每次请求的 X-Route-Model 覆盖，实时 Arena-ELO + models.dev 模型情报，每步账户白名单，提供商通配符组合步骤，嵌套组合引用执行，粘滞加权选择，web_search 感知路由，以及每次请求的自动组合控制（X-OmniRoute-Mode 模式预设覆盖 + X-OmniRoute-Budget 硬性美元成本上限，作用于单次请求）。 → 自动组合
🗜️ 可插拔压缩——由 10 个可组合引擎构成的异步管道，配备压缩工作室、LLMLingua-2 ONNX 引擎和启发式/SLM 两级极致、RTK、委托 Anthropic 上下文编辑、输出风格（输出轴转向：简洁-散文/减少代码/简洁-中日韩），自适应上下文预算拨盘（仅将压缩升级到适配上下文窗口所需的程度），每次请求的 x-omniroute-compression 控制，可选的离线评估框架，从仪表板一键管理余量代理生命周期（支持 Docker Sidecar），合成压缩演练场（演练通道 + A/B 对比，附带以美元封顶的保真度裁决），可选的每步保真度门，在损失性引擎降低提示质量前予以拒绝，候选编码器择优（GCF vs TOON——保留较短的输出，并在工作室中提供 A/B 字节/令牌对照表），CCR ranged/grep/stats

English / 原文

💰 ~1.6B 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 40+ provider pools / 500+ models into one honest number and shows it live on the dashboard (/dashboard/free-tiers).

~1.6B free tokens / month (steady) — and up to ~2.1B in your first month with signup credits.
Pool-deduped, honest — we count each shared free pool once , so the headline isn't inflated by rate-limit ceilings the way multi-billion competitor claims are. (Counting every rate limit 24/7 would read ~10B; we don't publish that.)
Plus the un-countable — permanently-free, no-token-cap providers (SiliconFlow, Z.AI GLM-Flash, Kilo, OpenCode Zen…) and a $10 OpenRouter top-up that unlocks +24M/mo , both surfaced separately so they never inflate the headline.
Per-model breakdown , live used / remaining for the current month, and a transparent terms flag per provider.

Preview mockup — a real screenshot lands once the /dashboard/free-tiers page is validated. Full methodology (pool dedupe, credit tiers, provider terms): docs/reference/FREE_TIERS.md.

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

🚫 Never hit limits
Auto-fallback across 237 providers in milliseconds. Quota out? Next provider takes over — zero downtime. | 💸 Save up to 95% tokens
RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions). | 🆓 $0 to start
90+ providers with a free tier, 11 free forever (Kiro, Qoder, Pollinations, LongCat…). No card needed.
---|---|---
🔌 Every tool works
24+ coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config. | 🧩 One endpoint
OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at /v1 and it just works. | 🛡️ Production-grade
Circuit breakers, TLS stealth, MCP (95 tools), A2A, memory, guardrails, evals. 21,000+ tests.

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

❌ The daily pain	✅ How OmniRoute fixes it
📉 Subscription quota expires unused every month	Maximize subscriptions — track quota, use every token before reset
🛑 Rate limits stop you mid-coding	4-tier auto-fallback — Subscription → API → Cheap → Free, in milliseconds
🔥 Tool outputs (`git diff`, `grep`, logs) burn tokens	RTK + Caveman compression — save 15–95% eligible tokens per request
💸 Expensive APIs ($20–50/mo per provider)	Cost-optimized routing — auto-route to the cheapest viable model
🧰 Each AI tool wants its own setup	One endpoint, every tool, one dashboard
🌍 AI blocked in your country	3-level proxy + TLS fingerprint stealth — use AI from anywhere

┌──────────────────────────────────────────────────────────┐
│        Your IDE / CLI  (Claude Code, Cursor, Cline…)       │
└─────────────────────────┬──────────────────────────────────┘
                          │ http://localhost:20128/v1
                          ▼
┌──────────────────────────────────────────────────────────┐
│                  OmniRoute — Smart Router                  │
│  RTK + Caveman compression · 17 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. 🛡️

⚡ 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 — 17 routing strategies

All 17 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 | lkgp | Last-Known-Good Path — sticky to the last successful target
16 | auto | 9-factor live scoring across every connection 🤖
17 | fusion | Fan out to a panel of models + a judge synthesizes one answer 🧬

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

⚖️ Quota-Share — split one subscription across a team ✨ NEW

Running several keys against the same upstream account (one Codex Pro plan, one Kimi key, one GLM Coding seat)? A burst on one key can burn the whole 5-hour / hourly quota and lock everyone else out. Quota-Share distributes a provider's time-based quota fairly across the keys in a pool — and it's work-conserving , so an idle member's slice is lent out instead of wasted.

Knob	What it controls
⚖️ Allocation weight	each key's slice of the pool — e.g. `50 / 30 / 20`
📐 Dimensions	track `%` · requests · tokens · `$`, per 5h / 7d / per-model window
🚦 Policy	`hard` (block over share) · `soft` (deprioritize) · `burst` (use idle headroom)
🧱 Cap	absolute ceiling per key, independent of mode

Pool "team-codex"   ·   1 Codex Pro account   ·   3 keys   ·   5-hour window
  ├─ alice    weight 50  ██████████░░░░░░░░░░   ≤ 50% of the shared 5h quota
  ├─ bob      weight 30  ██████░░░░░░░░░░░░░░   ≤ 30%
  └─ ci-bot   weight 20  ████░░░░░░░░░░░░░░░░   ≤ 20%
Generous mode (<50% pool used) → idle shares are lent out
Strict mode  (≥50% pool used)  → each key held to its fair share

Enforced in the hot path before the request leaves OmniRoute, with per-(key, model) caps + session stickiness for prompt-cache integrity. 📖 Quota Sharing Engine

🧱 Resilience is built in (3 independent layers)

Layer	Scope	What it does
🔌 Circuit breaker	whole provider	Stops hammering a provider that's failing upstream; auto-probes to recover
💤 Connection cooldown	one account / key	Skips a rate-limited key while other keys keep serving
🎯 Model lockout	provider + model	Quarantines just one quota-limited model, not the whole connection

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

🏆 What Sets OmniRoute Apart

Feature	OmniRoute	Other routers
🌐 Providers	237	20–100
🆓 Free providers	90+ (11 free forever)	1–5
🔀 Routing strategies	17 (priority, weighted, cost-optimized, context-relay, fusion…)	1–3
🗜️ Token compression	RTK + Caveman stacked (15–95%)	None / 20–40%
🧰 Built-in MCP server	95 tools, 3 transports, 30 scopes	Rare
🤝 A2A agent protocol	6 skills, JSON-RPC 2.0	None
🧠 Memory (FTS5 + vector)	Yes	Rare
🛡️ Guardrails (PII, injection, vision)	Yes	Rare
☁️ Cloud agents	Codex, Cursor, Devin, Jules	None
🥷 TLS fingerprint stealth	JA3/JA4 via wreq-js	None
🖥️ Multi-platform	Web · Desktop · Termux · PWA	Web only
🌍 i18n	42 locales	0–4

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

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

🗜️ Compression hardening — a default-on inflation guard (discard the stacked result and send the verbatim original whenever compression would grow the prompt), completed Caveman rule packs for German / French / Japanese (dedup + ultra) plus a new Chinese (文言 / wényán) input pack with zh-vs-ja auto-detection, and RTK filters for Gradle & .NET (dotnet) build output. → Compression
💸 Honest flat-rate cost — subscription / coding-plan providers (ChatGPT Web, grok-web, the Minimax / Kimi / GLM / Alibaba Coding plans, Xiaomi MiMo…) now read $0 in cost analytics instead of an inflated per-token estimate, while budget / quota / routing keep estimating unchanged. → API Reference
⚖️ Quota-Share routing — a dedicated combo strategy that spreads load across accounts by available quota : Deficit-Round-Robin scheduling, per-connection max_concurrent with cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key, model) caps, session stickiness for prompt-cache integrity, and proactive saturation from upstream token-usage headers. → Resilience Guide
🤖 One-command CLI/agent setup — a dedicated setup-* command configures each coding tool to route through OmniRoute (Claude Code, Codex, Cline, Continue, Cursor, Roo Code, Kilo Code, Crush, Goose, Qwen Code, Aider, OpenCode); omniroute launch / omniroute launch-codex are zero-config launchers. → CLI Integrations
🛰️ Remote mode — drive a remote OmniRoute from any machine with scoped access tokens (omniroute connect / omniroute contexts / omniroute tokens), plus an omniroute login antigravity helper that runs Google "native/desktop" OAuth on your own machine and pastes a credential blob into a remote/VPS install (where the loopback redirect is unreachable). → Remote Mode
🧭 Smarter auto-routing — OpenRouter-style auto/<category>:<tier> combos (e.g. auto/coding:fast, auto/reasoning:pro), a Fusion strategy (fan out to a panel of models in parallel, then synthesize via a judge), task-aware routing (best-fit connection per task type), per-request X-Route-Model override, live Arena-ELO + models.dev model intelligence, per-step account allowlists, provider-wildcard combo steps, nested combo-ref execution, sticky weighted selection, web_search-aware routing, and per-request Auto-Combo controls (X-OmniRoute-Mode mode-preset override + X-OmniRoute-Budget hard USD cost ceiling, scoped to a single request). → Auto-Combo
🗜️ Pluggable compression — an async pipeline of 10 composable engines with Compression Studios, an LLMLingua-2 ONNX engine and a heuristic/SLM two-tier Ultra , RTK, delegated Anthropic Context Editing, Output Styles (output-axis steering: terse-prose / less-code / terse-CJK), an adaptive context-budget dial (escalate only as far as needed to fit the context window), per-request x-omniroute-compression control, an opt-in offline eval harness, one-click Headroom proxy lifecycle management from the dashboard (Docker sidecar supported), a synthetic compression playground (Play lanes + A/B Compare with USD-capped fidelity verdicts), an opt-in per-step fidelity gate that rejects a lossy engine before it degrades the prompt, a best-of-N candidate encoder (GCF vs TOON — keep whichever is shorter, with an A/B bytes/token table in the studio), CCR ranged/grep/stats retrieval (pull an exact byte/line slice or summary of a stored block instead of re-expanding it), a unified panel with named profiles + an active-profile selector, an opt-in per-engine pipeline circuit-breaker , an opt-in LLM-tier engine (a model pass for higher-ratio semantic compression), a read-lifecycle engine that collapses superseded file reads, usage-observed prefix freeze , a graduated CCR retrieval-feedback ramp , a preserveSystemPrompt mode enum, and a drag-reorder pipeline editor in the studio. → Compression
🕵️ Transparent MITM decrypt (TPROXY) — capture & translate traffic from CLIs that ignore proxy env vars, with a per-SNI certificate authority and a trust-store installer. → MITM/TPROXY
💸 Cost telemetry everywhere — X-OmniRoute-* cost/usage headers on every endpoint (including media), a non-token cost engine, a cache-HIT X-OmniRoute-Cost-Saved header, and per-key USD spend quotas. → API Reference
🧠 Memory you control — opt-in int8 vector quantization (Qdrant + sqlite-vec), opt-in typed memory decay (aged low-value memories fade on a per-type schedule), memory off by default, and a per-request x-omniroute-no-memory header. → Memory
🛡️ Security — a prompt-injection guard across every LLM route (backed by a red-team suite), plus a free DuckDuckGo last-resort web search. → Guardrails
🖼️ New endpoints — /v1/ocr (Mistral OCR) and /v1/audio/translations (Whisper-style audio translation) round out the media API surface. → API Reference
🌍 Deployment & ops — reverse-proxy basePath deployment (OMNIROUTE_BASE_PATH, e.g. serving OmniRoute under /omniroute/), browser-language auto-detect on first visit, and per-API-key device/connection tracking (IP+UA fingerprint, masked, in-memory only). → Environment
🤝 More providers & agents — Cursor Cloud Agent (a 4th cloud agent), CodeBuddy CN (copilot.tencent.com), a Google Flow video-generation provider, new gateways DGrid and Pioneer AI (Fastino Labs), inbound xAI Grok translators plus Grok Build (xAI) with an OAuth import-token flow, GPT-4 / GPT-4o-mini on the GitHub Copilot provider, multi-model Factory Droid , ZenMux Free (session-cookie free tier), Alibaba DashScope text-to-video (wan2.7-t2v), a refreshed 237-provider catalog (OrcaRouter, Wafer AI, OpenAdapter, dit.ai, TokenRouter, …), Vertex AI media generation (speech/transcription/music/video), a first-class Ollama local-provider card, the SenseNova free Token Plan (chat + text-to-image), one-click account import from CLIProxyAPI (~/.cli-proxy-api/), Claude Sonnet 5 wired end-to-end, a new provider wave (Kenari , SumoPod , X5Lab , Charm Hyper , Nube.sh , b.ai , Qiniu , ModelScope , Augment/Auggie CLI , ClinePass , NVIDIA NIM image generation), and Codex account import from a raw ChatGPT access token. → Providers
⚡ Local performance & infra — a one-click local Redis launcher (omniroute redis up, plus a dashboard Redis panel), one-click Cloudflare Workers and Deno Deploy relay deployers wired into the proxy pool, a relay-backend selector (OMNIROUTE_RELAY_BACKEND=ts|bifrost|auto) so /v1/relay stays the stable surface while choosing the fastest backend internally, Bifrost (Go AI-gateway) and Mux (agent-orchestration daemon) promoted to first-class embedded/supervised services alongside 9Router/CLIProxyAPI, and Webshare added as a paid fourth source in the free-proxy provider framework. → Embedded Services

🤖 Compatible CLIs & Coding Agents

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

＋ also works with · Cline · Antigravity · Windsurf · AMP · Hermes · Qwen CLI · Roo · Continue · any OpenAI-compatible tool

📖 Per-tool setup for all 24+ tools → docs/reference/CLI-TOOLS.md · 🧩 OpenCode plugin → @omniroute/opencode-provider

🌐 237 AI Providers — 90+ Free

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

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

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 80+ commands , plus open agent protocols so an AI agent can drive OmniRoute by itself.

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

providers · oauth · keys · combo · nodes · models · cache · compression · cost · usage · quota · health · resilience · telemetry · logs · audit · mcp · a2a · cloud · memory · skills · eval · tunnel · backup · sync · webhooks · policy · pricing · translator · simulate …

🤝 Connect an agent — and it controls OmniRoute itself

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

Protocol	Endpoint	Use it for
🧰 MCP (stdio)	`omniroute --mcp`	Plug into Claude Desktop, Cursor, any MCP client
🌊 MCP (HTTP)	`http://localhost:20128/api/mcp/stream`	Remote MCP — 95 tools , 30 scopes, full audit trail
📡 MCP (SSE)	`http://localhost:20128/api/mcp/sse`	Streaming MCP transport
🤝 A2A	`http://localhost:20128/.well-known/agent.json`	Agent-to-agent, JSON-RPC 2.0 + SSE, 6 skills

# 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

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 10 composable engines that run in order and mix & match per routing combo — building on ideas from RTK, Caveman (⭐ 78K+), LLMLingua-2, and Troglodita (PT-BR).

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 | RTK | Smart tool-result filtering, dedup & truncation (command-aware)
4 | Headroom | Lossless tabular compaction of homogeneous JSON arrays (~30%+)
5 | Relevance | Extractive sentence scoring against the last user query
6 | Caveman | Rule-based prose compression (~65–75% on output)
7 | LLMLingua-2 | ML semantic pruning via MobileBERT ONNX — code-safe, async
8 | Lite | Whitespace + image-URL trimming (latency-light baseline)
9 | Aggressive | Summarization + progressive aging of old turns
10 | Ultra | Heuristic token pruning with an optional small-model (SLM) tier

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). UsaruseMemo."

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

📖 How it works — pipeline, architecture & savings math

Client (10,000 tok) ──▶ OmniRoute Compression (10 engines) ──▶ 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.

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

The 10 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

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

🇧🇷 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.

💰 Pricing at a glance & the $0 Free Stack (11 providers)

Tier	Example	Cost
💳 Subscription	Claude Code Pro / Codex / Copilot	$10–200/mo
🔑 API Key (free tiers)	NVIDIA NIM, Cerebras, Groq	FREE
💰 Cheap	GLM-5 $0.5/1M · MiniMax M2.5 $0.3/1M	pennies
🆓 Free Forever	Kiro, Qoder, Qwen, Pollinations, LongCat	$0

The $0 Free Stack — combine into one unbreakable combo:

Provider	Prefix	Free models	Quota
Kiro	`kr/`	Claude Sonnet 4.5, Haiku 4.5, Opus 4.6	50 credits/mo
Qoder	`if/`	kimi-k2-thinking, qwen3-coder-plus, deepseek-r1	♾️ Unlimited
Qwen	`qw/`	qwen3-coder-plus/flash/next	♾️ Unlimited
Pollinations	`pol/`	GPT-5, Claude, Gemini, DeepSeek, Llama 4	No key needed
LongCat	`lc/`	LongCat-2.0	10M one-time (KYC)
Cloudflare AI	`cf/`	50+ models	10K neurons/day
NVIDIA NIM	`nvidia/`	129 models	~40 RPM
Cerebras	`cerebras/`	Qwen3 235B, GPT-OSS 120B	1M tok/day

💡 The dashboard "cost" is a savings tracker , not a bill — OmniRoute never charges you. A "$290 total cost" using free models means $290 saved.

📖 Complete free directory → docs/reference/FREE_TIERS.md — 25+ providers, quotas, base URLs.

🎯 Use Cases — ready-made combo playbooks

$0 forever:

1. kr/claude-sonnet-4.5   (Kiro — ~50 credits/mo per acct)
2. if/kimi-k2-thinking    (Qoder — unlimited)
3. pol/gpt-5              (Pollinations — no key)
4. lc/LongCat-2.0         (10M one-time backup, KYC)
Compression: aggressive (~50%) → double your free quota · Cost: $0/mo

24/7 no interruptions: chain 2 subscriptions → cheap → free for 5 layers of fallback. Blocked region: free providers + global/per-provider proxy → access AI from any country. Max savings: subscription + cheap backup + ultra compression (~75%) → ~$150–300/mo saved for heavy users.

🌍 Bypass geo-blocks — 3-level proxy + stealth

🇷🇺 🇨🇳 🇮🇷 🇨🇺 🇹🇷 In a blocked region? OmniRoute's 3-level proxy (Global / Per-Provider / Per-Connection) proxies API requests, OAuth flows, connection tests, token refresh & model sync.

Protocols: HTTP/HTTPS, SOCKS5, authenticated proxies
🆓 1proxy marketplace — hundreds of free validated proxies, quality scores, auto-rotation
Anti-detection — TLS fingerprint spoofing (wreq-js), CLI fingerprint matching, proxy IP preservation

📖 docs/ops/PROXY_GUIDE.md

✨ Full feature list — 30+ capabilities (memory, evals, observability)

Routing: 17 strategies · task-aware smart routing · thinking budget controls · wildcard routing · system prompt injection. Compatibility: OpenAI ↔ Claude ↔ Gemini ↔ Responses API · auto OAuth refresh (PKCE, 8 providers) · multi-account round-robin · Batch + Files API · live OpenAPI 3.0. Protocols: MCP (95 tools, 3 transports, 30 scopes) · A2A (JSON-RPC 2.0, SSE, 6 skills) · ACP · cloud agents (Codex, Cursor, Devin, Jules). Plugins: custom plugin marketplace (system-configured registry URL with SSRF-guarded fetch) · install / enable / disable · Notion + Obsidian knowledge-base integrations (WebDAV file server, vault search, note CRUD). Embedded services: one-click install & lifecycle management of local sidecar services (CLIProxy, NineRouter). Quality & Ops: built-in Evals (golden-set: exact/contains/regex/custom) · guardrails (PII, injection, vision) · health dashboard · p50/p95/p99 telemetry · webhooks · compliance audit. AI Agent Skills: drop-in markdown manifests — point any agent at a skills/*/SKILL.md manifest. 43 skills available.

📖 MCP Server · A2A Server · Resilience Guide · Features Gallery

📖 Setup, env vars & FAQ

Env var	Default	Purpose
`PORT`	`20128`	API + dashboard port
`REQUIRE_API_KEY`	`false`	Require API key for all requests
`DATA_DIR`	`~/.omniroute`	Database & config storage

Will I be charged by OmniRoute? No — it's free, open-source software on your machine. You only pay paid providers directly. OmniRoute has no billing system. Are FREE providers really unlimited? Mostly — Qoder, Pollinations, LongCat, and Cloudflare are free with no per-account credit cap. Kiro is free too but capped at ~50 credits/month per account. Stack multiple free providers in a combo and auto-fallback keeps you serving for $0. Will compression hurt quality? No — it only compresses the input ; code, URLs, JSON are always protected. Does it work where AI is blocked? Yes — 3-level proxy + 1proxy marketplace reach all 237 providers.

📖 User Guide · API Reference · Environment Config

🐛 Troubleshooting

Problem	Quick fix
"Language model did not provide messages"	Provider quota exhausted → use a combo fallback
Rate limiting (429)	Add fallback: `cc/claude → glm/glm-4.7 → if/kimi-k2-thinking`
OAuth token expired	Auto-refreshed; if stuck, delete + re-auth in Providers
`unsupported_country_region_territory`	Configure proxy in Settings → Proxy
Docker SQLite locks	Use `--stop-timeout 40` for clean WAL checkpoint
Node runtime errors	Use Node `>=22.0.0 <23` or `>=24.0.0 <27`

🐛 Reporting a bug? Run npm run system-info and attach system-info.txt. 📖 docs/guides/TROUBLESHOOTING.md

📸 Dashboard screenshots

Page	Screenshot	Page	Screenshot
Providers		Combos
Analytics		Health
Translator		Settings
CLI Tools		Usage Logs

📧 Support & Community

💬 Chat with the community — Discord, Telegram & WhatsApp (🌍 / 🇧🇷) links are at the top of this README.

Runtime : Node.js 22.x or 24.x LTS (24 LTS recommended) — >=22.0.0 <23 || >=24.0.0 <27
Language : TypeScript 6.0 — 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 (21,000+ test cases across 2,586 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

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

🧠 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	9-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
Document	Description
---	---
API Reference	All endpoints with examples
OpenAPI Spec	OpenAPI 3.0 specification
MCP Server	95 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

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
🥇 189 commits • +155K lines
Analytics engine, SQL aggregations,
proxy marketplace, test coverage |
Chris Staley
🥈 70 commits • +5.7K lines
SSE stream hardening, Responses API,
Gemini pagination, test regression fixes |
zenobit
🥉 62 commits • +24K lines
CI/CD pipeline, i18n for 33 languages,
Void Linux package, platform fixes |
R.D. & Randi
🏅 108 commits • +30K lines
Endpoints page, tunnel integrations,
Docker workflows, A2A status, compression UI |
benzntech
🏅 22 commits • +7.5K lines
Electron desktop app, auto-updater,
release build workflows, cross-platform CI |
herjarsa
🏅 21 commits • +6K 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.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

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 June 2026 — go give these projects a star.

Project	⭐	How it inspired OmniRoute
9router · decolua	19.0k	The original project this fork is built on — extended here with multi-modal APIs and a full TypeScript rewrite.
CLIProxyAPI · router-for-me	38.8k	The Go implementation that inspired this JavaScript / TypeScript port.
LiteLLM · BerriAI	52.1k	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 · JuliusBrussee	78.2k	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 · rtk-ai	67.3k	High-performance command-output compression — inspired our RTK engine, JSON filter DSL, raw-output recovery and the stacked RTK → Caveman pipeline.
headroom · headroomlabs-ai	54.5k	Reversible context-compression (SmartCrusher) — inspired our `headroom` engine and the `ccr` retrieve-marker pattern.
LLMLingua · Microsoft	6.4k	Prompt-compression research (LLMLingua / LLMLingua-2) — inspired our async, code-safe, fail-open `llmlingua` engine.
llmlingua-2-js · atjsh	28	The JS/ONNX port (MobileBERT / XLM-RoBERTa) used as the worker-thread backend for our LLMLingua engine.
Troglodita · Lenine Júnior	16	PT-BR token compression — powers our pt-BR language pack: pleonasm reduction and filler removal tuned for Brazilian-Portuguese grammar.
ponytail · DietrichGebert	68.8k	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 · toon-format	24.7k	Token-Oriented Object Notation — its columnar, header-plus-rows model shaped our tabular compaction stage.
GCF – Graph Compact Format · Blackwell Systems	14	Schema-aware "JSON for LLMs" notation — co-inspired our lossless homogeneous-array compaction with `[N rows]` markers.
token-optimizer-mcp · ooples	421	Brotli/SQLite cache + per-session context-delta — inspired our `session-dedup` engine.
token-savior · Mibayy	1.0k	Bash-output compaction + MCP profiles — inspired our compression bail-out discipline and MCP tool-manifest reduction.
token-saver · ppgranger	110	Content-aware, per-file-type output compression with failure-aware bail-out — validated our per-type dispatch and minimum-gain skip.
token-optimizer · alexgreensh	1.5k	"Find the ghost tokens" — its offload + recoverable-handle pattern informed our CCR offload thinking.
TokenMizer · Shweta-Mishra-ai	2	A session-graph + cross-turn line-dedup blueprint that informed our session-dedup design.
OmniCompress · jessefreitas	2	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 · Atlassian Labs	89	MCP tool-schema/description compression — informed our MCP tool-manifest cardinality reduction.
RepoMapper · pdavis68	181	Aider-style repo-map ranking — informed our repo-map / retrieval-ranking exploration.
quiet-shell-mcp · mrsimpson	4	Declarative shell-output reduction over MCP — validated our declarative bash-output compaction.
ts-morph · David Sherret	6.1k	TypeScript Compiler API toolkit — inspired our parser-based comment removal that preserves string, template and regex literals.
Project	⭐	How it inspired OmniRoute
---	---	---
Mem0 · mem0ai	59.8k	Universal memory layer — its proxy-as-write/read-boundary model shaped our memory architecture.
Letta (MemGPT) · letta-ai	23.6k	Stateful agents with tiered memory — inspired our Context Control & Recovery (CCR) tiered model.
WFGY · onestardao	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 · chouzz	48	MITM interception/analysis of coding-assistant ↔ LLM traffic — our Traffic Inspector ports its SSE merge, conversation normalization, host passthrough and secret masking (MIT).
ProxyBridge · InterceptSuite	5.3k	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 · SST / OpenCode	5.6k	Open database of AI model specs, pricing and capabilities — synced natively into our model catalog.
React Flow / xyflow · xyflow	37.4k	The node-based graph library powering our real-time Compression Studio and Combo/Routing Studio.
LangGraph · LangChain	36.1k	LangGraph Studio's live workflow-graph visualization inspired our Studios' real-time cascade view.
Langfuse · Langfuse	30.1k	Its trace → span → generation observability model shaped our Compression Studio waterfall.
Kiali · Kiali	3.6k	Istio service-mesh observability — inspired our circuit-breaker badges and error-edge visuals in the Routing/Combo Studio.
lobe-icons · LobeHub	2.2k	AI/LLM brand logos that render the provider icons across our dashboard.
Project	⭐	How it inspired OmniRoute
---	---	---
awesome-secure-defaults · tldrsec	708	A curated list of secure-by-default libraries that guides our security choices (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink).

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

MIT License - see LICENSE for details.