The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
npx ecc-install --profile fullFair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
npx n8nAn open-source AI agent that brings the power of Gemini directly into your terminal.
npx @google/gemini-cligit checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)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
Carries strong trust indicators from repository metadata
14298 GitHub stars recorded
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 (now with a per-combo / global disable toggle). π Quota Sharing Engine
| 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
| 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.45. Full history in
CHANGELOG.md.
dotnet) build output. β Compressionmax_concurrent with cooldown-wait queueing, multi-window usage buckets (5h / 7d / per-model), per-(key, model) caps, session stickiness for prompt-cache integrity (now with a per-combo / global disable toggle), and proactive saturation from upstream token-usage headers. β Resilience Guidesetup-* 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 Integrationsomniroute 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 Modeauto/<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-Combox-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. β CompressionX-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 Referencex-omniroute-no-memory header. β Memory/v1/ocr (Mistral OCR) and /v1/audio/translations (Whisper-style audio translation) round out the media API surface. β API ReferencebasePath deployment (OMNIROUTE_BASE_PATH, e.g. serving OmniRoute under /omniroute/), browser-language auto-detect on first visit, per-API-key device/connection tracking (IP+UA fingerprint, masked, in-memory only), root-less MITM cert trust for user-namespaced containers (OMNIROUTE_NO_SUDO), and server-side configured-only / available-only filters on the Free Provider Rankings page. β Environmentcopilot.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), Codex account import from a raw ChatGPT access token, the Requesty gateway (BYOK, ~200 free req/day), Yuanbao (web) as a cookie-session provider (DeepSeek V3/R1 + Hunyuan), the Zed hosted LLM aggregator (OAuth), Claude 5 Sonnet on the Claude Web provider, Kiro adaptive-thinking reasoning surfaced as reasoning_content, and bulk API-key add for Cloudflare Workers AI. β Providersomniroute 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 ServicesOne config β
http://localhost:20128/v1β and every AI IDE or CLI runs on free & low-cost models.
π Per-tool setup for all 24+ tools β docs/reference/CLI-TOOLS.md Β· 𧩠OpenCode plugin β @omniroute/opencode-provider
The most complete catalog of any open-source router: 237 providers, 90+ with a free tier, 11 free forever.
β¦and 220+ more β every icon resolves live from the dashboard's provider catalog. π Provider Reference
π Full machine-readable catalog β docs/reference/PROVIDER_REFERENCE.md
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.
π 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.
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
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 β¦
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
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). Usar
useMemo."Mesma resposta. ~70% menos tokens. PrecisΓ£o tΓ©cnica intacta. β
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.
The 10 engines above shrink what goes in. Three more layers shape how, when, and what comes out:
lite / full / ultra intensity. Adding a style is a one-line registry entry:
zh).reserve-output (default, model-aware) Β· percentage Β· absolute. Mode: floor (guarantee fit) Β· replace-autotrigger (your explicit choice wins) Β· off (legacy threshold).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.
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.
| 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 |
| 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 |
| Document | Description |
|---|---|
| Contributing | Development setup and guidelines |
| 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 21,000+ test suite |
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.
π 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.