What Is OmniRoute? Setup with Claude Code, Free Models and Risks
You point coding tools such as Claude Code, Codex and Cline at a single local address (http://localhost:20128/v1); OmniRoute, running on your own computer, distributes requests to the providers you connect and moves to the next one when a quota runs out or an error occurs. It is MIT-licensed open source; it installs via npm, Docker or a desktop app and requires terminal knowledge. The software is free but the models are not: a "free quota" is the quota of the accounts you connect, not something OmniRoute provides. Provider terms and account risk are on you.
- What it does
- Routes coding tools to providers from a single address
- Type
- Local gateway (open source)
- Software
- Free (MIT)
- Model cost
- Set by the providers; OmniRoute doesn't supply it
- No-code
- Partly; dashboard in the browser, setup in the terminal
- Risk
- Provider terms and account risk are on you
- Latest version
- v3.8.51 (September 30, 2026)
What is OmniRoute for? Can I use it without code?
Each AI coding tool (such as Claude Code, Codex, Cline) connects to its own provider. OmniRoute sits between them: it opens a single address running on your computer, the tools connect to that address, and OmniRoute sends the request to one of the providers you have connected. When one returns a quota error or fails, it automatically tries the next. Tools of this kind are called "gateways". The dashboard and settings open in the browser.
Partly. After setup, adding providers, copying keys and settings are done in the browser dashboard (http://localhost:20128). But installation needs either Node.js and a terminal command (npm install -g omniroute), Docker, or the desktop installer; entering the address and key in your tools is also up to you. If you have no technical knowledge at all, this tool is not for you.
Who it's for: developers and advanced users who use several AI providers and want to manage quotas and costs in one place. The README promises "savings" and "never stop"; these are the maker's claims. This guide reports everything as stated.
The number of providers differs between documents (README 372, repo description 359, omniroute.online 352), so no exact number is given. Watch the name: searches for "omni router" can surface other products too; this page is about diegosouzapw/OmniRoute on GitHub.
How to install OmniRoute: which version and hardware?
The latest released version is v3.8.51 (September 30, 2026, GitHub Releases and npm). The repository's default branch shows 3.8.52; that is an unreleased development branch.
Node.js must be 22.22.2 or later (22.x) or 24 or later (before 27) (package.json).
› npm install -g omniroute
omnirouteThe dashboard opens at http://localhost:20128, the API at http://localhost:20128/v1. npm warnings (ERESOLVE) are harmless. If you use npm 11, you may need to allow the required packages with the --allow-scripts command in the README.
› 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| Workload | Memory setting | Container (--memory) |
|---|---|---|
| Dashboard, light chat | 1024 (image default) | at least 2 GB |
| One coding tool | 8192 (OMNIROUTE_MEMORY_MB) | at least 10 GB |
| Two long requests at once | 10240 to 12288 | at least 12 to 16 GB |
Values are from the Docker section of the README. The default memory may not be enough for coding tools.
The Releases page has OmniRoute.Setup.3.8.51.exe for Windows (about 0.58 GB), a .dmg for macOS, and .AppImage and .deb files for Linux.
!The troubleshooting document says the Windows installer is not yet code-signed and may trigger an antivirus or SmartScreen warning. Download the file only from the official GitHub Releases page.
!For admin login, INITIAL_PASSWORD is set in the .env file (troubleshooting document: there is no hard-coded default password). Don't write the password down anywhere or share it.
Setup information is from the README, package.json and the troubleshooting document (October 15, 2026).
How to use OmniRoute: Claude Code, Codex, VS Code and your own code
First, in the dashboard's Providers section, add a provider whose terms suit you (enter an API key or sign in with your account). Then copy the OmniRoute key from the Endpoints section. Tools connect to the local address with this key; your provider keys stay in OmniRoute.
› omniroute run claude --model <provider>/<model>Instead of claude you can write codex, aider, goose, opencode, qwen, gemini. Replace the model name in the README example with the model name of the provider you connected. Nothing is written to config files; credentials are passed per process.
› omniroute configure codexThe configure command also works for claude, opencode, qwen, aider, goose, gemini, cline, continue and kilo. You can add --dry-run to see what it will do, and --api-key-env NAME to keep the key out of your shell history.
In any OpenAI-compatible tool that accepts an address and key, enter:
- Base URL:
http://localhost:20128/v1 - API Key: the OmniRoute key you copied from Dashboard > Endpoints
- Model:
auto(picks among suitable connected providers) orprovider/model
For tools that can't send a header (Authorization), the README also gives alternative addresses that embed the key in the URL. Since the key is visible in the address, use them only if you must; sending it in the header is the preferred way.
According to the README, you install the OmniCopilot extension and point it at your OmniRoute server (default localhost:20128); the models then appear via Copilot Chat > model picker > Manage Models… > OmniRoute. Since VS Code 1.122, provider models work without a GitHub login or Copilot subscription (README). The extension is on the VS Code Marketplace and Open VSX; through Open VSX it can also be installed in editors such as Cursor, Windsurf and VSCodium.
› curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"› curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'auto only works if there is a suitable connection; a fresh install may have no suitable target at all.
Commands are taken verbatim from the README (October 15, 2026). For detailed setup of each tool, the README provides a document covering 36 tools (docs/reference/CLI-TOOLS.md).
OmniRoute risks: accounts, data and commercial use. Does it work in Turkish?
- Use, modify and distribute the software commercially under the MIT license
- Use the providers you connect in line with their own account rules and terms
- Opening extra accounts to get around a provider's quota or access policy (the free tiers guide warns against it)
- Removing the copyright notice from copies you distribute
Each provider's terms of service, privacy policy and free-tier conditions apply separately. The free tiers guide mentions "account policy risk". Read that provider's current terms before connecting a subscription account (OAuth). This is not legal advice.
The gateway and dashboard run on your own machine, and telemetry is off by default. But your prompts go to the selected provider with every request; some free providers may log requests or use them for training. Credentials are stored encrypted, and a local audit log is kept.
The Docker command binds it so it is reachable only from this computer (127.0.0.1). If you open it to other devices, take the OmniRoute key and password seriously. The README recommends the alternative addresses that embed the key in the URL only for tools that can't send a header.
| Turkish dashboardYes | The repository has a Turkish translation file (tr.json) and a Turkish README (docs/i18n/tr). How complete the translation is isn't documented. |
|---|---|
| Replies in TurkishUnclear | OmniRoute passes the request to the selected model; the reply language and quality depend on the model. The official documentation doesn't say anything further. |
This section is not legal advice. The information is from the October 15, 2026 version of the README and official documents.
Is OmniRoute free? Are the "free models" really free?
The software is free (MIT). But OmniRoute doesn't supply models or tokens for you. The "about 1.62 billion tokens a month" figure at the top of the README is an estimated total of separate eligible third-party free tiers; the README itself says this is not an allowance OmniRoute provides. For each free quota, you sign up with that provider.
!Free tiers may require sign-up, approval, a payment method or identity verification. The "Is there a catch?" section of the Free Tiers Guide lists: strict limits, waitlists, KYC, credit card verification, prompts used for training, weak privacy, no SLA, model changes, geographic restrictions, paid overage and account policy risk.
| Example (from the guide, dated) | What it says |
|---|---|
| Cerebras | A one-time $5 credit that expires in 30 days and requires a payment method; not a recurring quota (the guide says it verified this on October 8, 2026). |
| OpenRouter | Free models have quota and request limits; an optional top-up raises the limit. |
| Logfare | Free key, but the guide says "every request is logged for research" (there is an opt-out link). |
| Kiro, OpenCode Free | Marked "tos: avoid"; excluded from automatic routing by default due to account terms risk, and connecting an account doesn't override this. |
No guarantee: the README says any provider may impose quotas, change models, suspend access or shut down. What "free" means varies by provider; check your own conditions on the provider's page. The guide also restricts multiple accounts: don't open extra accounts to exceed a provider's quota.
You run it on your own computer or server; the computer, electricity, server costs and updates are on you. No server cost is given here; the official sources don't provide one.
omniroute.online and the README sponsor section promote a paid gateway (Cheaper Inference); the site says its owner is involved in it. This is a promotion, it is not needed for setup and it is not recommended here.
Official pricing page last checked on .
Common OmniRoute problems: API key, login and error codes
| What happens | What to do (official troubleshooting) |
|---|---|
429 / "Rate limit exceeded" | Wait 1 minute or use automatic fallback with model: auto. |
| "Quota exceeded" | Your quota is used up; connect more providers. |
401 Unauthorized | Check your API key or sign in again with OAuth. |
502 Bad Gateway | The provider is down; wait or switch to another provider with auto. |
| Password doesn't work on first login | Set INITIAL_PASSWORD in the .env file. |
auto returns an error | A fresh install may have no suitable keyless target; connect at least one provider. "tos: avoid" providers are excluded from automatic routing. |
| "omniroute is not recognized" (Windows) | Add the npm global directory to PATH; find the path with npm config get prefix. |
| Windows installer flagged by antivirus | The installer is not yet code-signed; the documentation explains how to compare the file against the sha512 value in latest.yml. |
Frequently asked questions
What is OmniRoute and what is it for?
An MIT-licensed gateway that runs on your own computer, sends requests to many AI providers from a single OpenAI-compatible address and automatically switches to another provider when a quota runs out or an error occurs. The dashboard opens in the browser.
How do you use OmniRoute with Claude Code?
Install OmniRoute, add a provider in the dashboard, and either run omniroute run claude --model <provider>/<model> or set the tool's Base URL to http://localhost:20128/v1 and enter the OmniRoute key. Details are in the usage section.
How do you install OmniRoute?
With npm: npm install -g omniroute and then omniroute (Node.js 22.22.2, or 24 and later); with Docker: the diegosouzapw/omniroute image; or the desktop app. The dashboard opens at http://localhost:20128.
Is OmniRoute free, and are there free models?
The software is free (MIT). Free models are third-party providers' own quotas; they may require sign-up, a card or identity verification, and there is no guarantee. OmniRoute doesn't provide quota.
Where do I get an OmniRoute API key?
The OmniRoute key is copied from the Endpoints section of the dashboard. Provider keys you get from each provider's own site and enter in the Providers section. On a 401 error, check the key or sign in again.
Does OmniRoute work with VS Code and GitHub Copilot?
According to the README, with the OmniCopilot extension OmniRoute models appear in Copilot Chat's model picker; since VS Code 1.122 this doesn't require a GitHub login or Copilot subscription.
Related guides
Sources
- OmniRoute GitHub (README)
- Free Tiers Guide
- Troubleshooting
- Releases
- npm: omniroute
- omniroute.online
- OmniCopilot (VS Code extension)
Not clear in the official sources: Current quotas and terms of free providers · whether connecting subscription accounts complies with provider terms · the number of providers (differs between documents) · maker claims such as "15 to 95% token savings" (depends on content) · completeness of the Turkish dashboard translation and quality of Turkish replies · behavior of the desktop package · server cost (not given in the official sources) · the full issue tracker (444 open issues). Each is covered in its section, with what you can do.