OmniRoute is a gateway you run yourself. Install it with npm install -g omniroute, start it with omniroute, open the dashboard at http://localhost:20128, connect the providers you already have access to, and point your tools at http://localhost:20128/v1. The gateway is free. The tokens behind it are not, and the question that decides whether it saves you money is whose accounts sit behind it.
What OmniRoute is
Diego Souza created the project together with a large group of contributors. The repository diegosouzapw/OmniRoute was created on 13 February 2026, had about 86,000 GitHub stars on 10 November, and is MIT-licensed. Releases come every two to three weeks: v3.8.51 on 30 September, v3.8.52 on 19 October, v3.8.53 on 6 November.
It exposes one OpenAI-style endpoint and fans requests out across whatever you connect. The README counts 380 providers (the README on the v3.8.54 release branch already says 387 on 10 November, so the number moves with each release), 20 routing strategies, automatic fallback when a quota runs out, context compression, and MCP and A2A servers. Routing follows a four-step ladder: subscription, API key, cheap models, free models. A chain of models is called a combo. When one step runs dry or a provider fails, the combo moves to the next eligible one. The auto model builds that chain from your connected providers, and auto/coding, auto/cheap and auto/fast shift the priority.
What it does not do is stated plainly in the README: it does not issue tokens or sell access. You bring each provider account or key yourself.
Install and first run
| Method | Command |
|---|---|
| npm | npm install -g omniroute, then omniroute |
| 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 |
| pnpm | pnpm add -g omniroute@latest --allow-build=better-sqlite3 --allow-build=@swc/core && omniroute |
| Android | Termux: pkg install nodejs && npx -y omniroute |
The troubleshooting guide lists Node >=22.22.2 <23 and >=24.0.0 <27 as supported. npm 11 blocks install scripts, and OmniRoute's postinstall prepares its native files, so for version 3.8.53 the README gives this command:
npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute
The package list changes between releases, so use the one from npm's own warning. Allowing a package lets its install scripts run.
Memory is the quiet cost. The default Docker image is sized for the dashboard and light chat (a 1024 MB heap). For one coding agent the README advises OMNIROUTE_MEMORY_MB=8192 and a container of at least 10 GB; for two overlapping long contexts, a 10240 to 12288 MB heap and 12 to 16 GB. Without that the process can die with a FATAL ERROR.
Then connect something. Go to Providers and add a provider, copy the gateway key from Dashboard, Endpoints, and test it: curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY". The README warns that a fresh install may have no eligible keyless providers, so installing OmniRoute alone does not guarantee an answer.
Claude Code through OmniRoute
The shortest route writes no config:
omniroute run claude --model provider/model
omniroute launch also works: it takes the address and key from the active context and starts claude. By hand, put this in ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:20128",
"ANTHROPIC_AUTH_TOKEN": "YOUR_OMNIROUTE_KEY",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
}
}
Three details from the project docs. Write the address without /v1, because Claude Code appends /v1/messages itself. The variables are read once at startup, so restart the agent after editing. And Claude Code assumes a 200K window for model IDs it does not recognize, so for a model with a bigger window set CLAUDE_CODE_AUTO_COMPACT_WINDOW below its real window, or compaction fires at the wrong moment. The /model picker lists only IDs starting with claude or anthropic unless you switch on alias mirroring (EXPOSE_CC_DISCOVERY_ALIASES, off by default).
Which models you route there is a separate decision. Anthropic's gateway documentation says any gateway that exposes a supported API format works, and also says the company does not support routing Claude Code to non-Claude models through any gateway. If you send the agent to free GLM or Kimi models, some features may behave differently and you should not expect support from Anthropic.
What the free-token number means
The README headline says "~1.62B tokens / month." The note under it says this is an estimate across separate third-party free tiers, not a grant from OmniRoute. It is computed from 17 pools with a published monthly budget plus five per-model Groq caps, with shared pools counted once. The project re-audits it every two weeks and says it moves both ways. What you can actually use depends on the providers you connect.
The project's free-tier guide (edition of 11 October 2026) lists the catches itself:
| Provider | What the guide says | The catch |
|---|---|---|
| Groq | Pool estimated at about 15M tokens a month | Request rate limits apply |
| Cloudflare AI | Pool estimated at about 30M tokens a month | Needs an account and credentials |
| Gemini | No fixed monthly grant | Limits vary by project and model |
| Cerebras | One-time $5 credit, expires after 30 days | Needs a payment method |
| Logfare | Free key, no card | Every request is logged for research |
The same guide names the general trade-offs: strict limits, KYC, training on your prompts, weaker privacy, no SLA, model churn, regional restrictions. Any provider can cut a limit, swap a model, suspend access or go offline, and several connections improve coverage without guaranteeing a route.
Terms-of-service risk when you route other accounts
What the project says. The README and guides repeat one message: connect your own accounts, and each provider decides its own terms, limits and availability. Providers marked tos: avoid, Kiro among them, are excluded from auto-routing by default, and connecting an account does not lift that filter. The README counts 12 such providers. The guide says any override should follow a review of the provider's terms and the risk to your account. It also says not to create extra accounts to dodge a quota or an access policy.
Subscriptions. The project has providers that work through a Claude Code subscription (an OAuth token, including one from claude setup-token) and through your claude.ai session cookie. Its document on the Claude Code route says requests are rewritten on that path: a billing header and the line "You are Claude Code, Anthropic's official CLI for Claude" are prepended, tool names are remapped, paragraphs that identify another agent are removed, and words like cursor and cline get zero-width joiners. The stated reason is that without this, clients other than Claude Code hit the error "Third-party apps now draw from extra usage, not plan limits" on a subscription.
The project's stealth guide calls these features a compatibility layer between user-owned accounts and the OmniRoute API. By its text they are not meant for evading fraud detection, sharing credentials or breaking terms of service, and operators are expected to follow the terms they accepted when they opened the accounts. For the case where a provider does block an account, there is a detector: the connection moves to a banned state with a one-year stop and does not come back on its own.
What Anthropic says. The "Legal and compliance" page of the Claude Code docs, which we opened on 10 November 2026, separates two ways of signing in. OAuth is for buyers of subscription plans and covers ordinary use of Claude Code and Anthropic's native apps. Developers who build products are pointed to API keys. Third-party developers may not route requests through Free, Pro, Max or Ultra credentials on behalf of their users, nor collect, store or intermediate Claude.ai credentials and session tokens. Anthropic reserves the right to enforce this without notice, and says plan limits assume ordinary individual use.
Whether your own setup on your own machine falls under that wording is not ours to decide, and we make no legal call. Read the page. The practical difference is simple: on an API key paid per token the subscription question does not come up, although the API provider's own terms about countries and data still apply.
OmniRoute, LiteLLM, OpenRouter or one hosted key
| OmniRoute | LiteLLM (self-hosted) | OpenRouter | One Claudexia key | |
|---|---|---|---|---|
| Where it runs | Your machine or server | Your servers | Hosted | Hosted |
| Who supplies upstream access | You: accounts, subscriptions, keys | You: provider keys | The service | The service |
| Payment | Whatever each provider takes | Whatever each provider takes | Card and crypto | Card, SBP, crypto (USDT, BTC, ETH, TON), from $1 |
| Reach | 380 providers, 20 routing strategies | 100+ providers behind one API | Hundreds of models | Claude, GPT, DeepSeek and others from the catalog |
| Per-key budgets | Yes, USD spend quotas per key | Yes | Not checked | Not available in the key API |
| Upkeep | Yours: Node, updates, RAM | Yours: database, patches, on-call | None | None |
The LiteLLM and OpenRouter columns come from our earlier comparisons, Claudexia vs self-hosted LiteLLM and Claudexia vs OpenRouter, and the OmniRoute column from its README. We sell the last column, so weigh our view accordingly.
When one paid key is simpler
OmniRoute wins when you want your own routing strategies, dozens of providers, local models and full control over where each request goes, and you have the time to run it. A single paid key wins when predictability matters: one payment, one address, no server, no separate provider accounts to manage. People who arrive for free tokens and run into limits mid-session are usually in the second group. A hosted key has limits too: provider or channel policy can still return HTTP 429, so the client should retry with a delay.
Claudexia prices per token. As of 10 November 2026 on the Premium channel, claude-sonnet-5 costs 0.52 input and 1.98 output dollars per million tokens, and deepseek-v4.1-flash costs 0.06 and 0.22. Subscriptions to Claude or ChatGPT are not sold: access runs on a sk_cdx_ key paid per token. Provider terms about countries and data are not something we can waive.
The two can also be combined. OmniRoute's docs describe OpenAI-compatible provider nodes, whose models show up in /v1/models under the node prefix. Claudexia serves https://api.claudexia.tech/v1, a sk_cdx_... key and a catalog at GET /v1/models, so by description it should attach as such a node. We have not run that setup or verified the dashboard steps, so treat it as an idea, not a recipe. For the Claude Code side on our key, see the Claude Code setup guide, and for lowering the bill see how to cut a Claude Code bill.
FAQ
What is OmniRoute?
A local gateway under the MIT license. It exposes one OpenAI-compatible address at localhost:20128/v1 and routes requests across the providers you connect, with automatic fallback when a limit is hit. It does not sell tokens: you bring the provider accounts and keys.
How do I install OmniRoute?
Run npm install -g omniroute and then omniroute, or use the Docker image diegosouzapw/omniroute. The dashboard is at http://localhost:20128. If npm 11 blocks install scripts, use the --allow-scripts command shown above.
How do I connect Claude Code to OmniRoute?
Run omniroute run claude --model provider/model, or set ANTHROPIC_BASE_URL=http://localhost:20128 without /v1 and ANTHROPIC_AUTH_TOKEN to the gateway key. Restart Claude Code after changing the variables.
Is OmniRoute free?
The gateway is. The tokens are not: the 1.62 billion figure is an estimate across third-party free tiers, and each provider sets its own limits and terms. Some free options need a card or KYC.
OmniRoute is not working: what should I check?
By the project's own guide: is the process running (omniroute, or docker restart omniroute), is the key right, have you hit a provider limit (model: "auto" and a second provider help), and on Windows is the folder from npm config get prefix on PATH. omniroute doctor diagnoses providers, ports and native dependencies.
Is it safe to route a Claude subscription through OmniRoute?
Anthropic's terms separate subscriptions from API keys and do not let third-party developers route requests through subscription credentials on behalf of users. Whether that covers your case is for them to say, not us. A setup on an API key paid per token does not raise the question.