OmniRoute is a router that runs on your own machine. You point Claude Code, Cursor or Codex at a single address, and behind it OmniRoute moves across more than 350 providers, switching to the next one when one hits a limit or throws an error. It is open source, MIT licensed and needs no account. The install is one line, but you get stuck in three places. First, the Node version: on an unsupported version the install looks finished and the dashboard opens blank. Second, Claude Code: the address you give other tools does not fit it, and the config command in the docs writes over your existing settings file. Third, picking a free provider: Kiro and OpenCode Free, the two the quick start suggests, are flagged "avoid" in the project's own terms of service table. Below: the verified install, a way to connect Claude Code without touching any file, and where to check which providers are clean to connect.
OmniRoute is an AI gateway. Your coding tool sends its request to it, and it forwards that to whichever of your connected providers fits. If a provider does not answer, runs out of quota or returns an error, it moves on to the next. Everything runs on your machine: your prompts do not pass through an OmniRoute server, they go straight to the selected provider, and your keys sit encrypted on disk.
What is extra below: which Node versions it runs on, why Claude Code connects differently from other tools, what the config command in the docs wipes out, and why the free providers the README suggests are flagged avoid in the project's own table.
Where a request goes
Your coding tool
Claude Code, Cursor, Codex, Cline. All pointed at one address.
OmniRoute, localhost:20128
Takes the request, picks which provider it goes to, tries the next one if something fails.
Providers
Your subscriptions first, then your API keys, then cheap tiers, and free tiers last.
If you set the model name to auto, OmniRoute decides which model gets used. There are variants too: auto/coding puts code quality first, auto/fast puts speed first, auto/cheap puts price first.
One thing to know up front: when you open Claude Code through OmniRoute, the interface is Claude Code but the model answering may not be Claude. Set your quality expectations accordingly. I went through the same distinction in more detail at number 110 in this archive.
It does not run on Node 20 or 23
Accepted versions are 22.22.2 and above on the 22 line, or 24, 25 and 26. Node 20, Node 23 and older 22 patches are not supported. On an unsupported version the install looks finished, but the dashboard opens blank or you get a Module did not self-register error. If you are unsure, install 24.
node -vnpm install -g omniroute
omnirouteThe second command starts the server and opens the dashboard in your browser: http://localhost:20128. OmniRoute runs for as long as that terminal stays open. Close it and your tools have no address to connect to.
During the install your screen fills with npm warn ERESOLVE and deprecated warnings. They are harmless, and the project's own docs say so. If you see the line starting with added that reports how many packages were added, the install worked.
omniroute doctor
# checks providers, the port and native dependenciesOn a fresh install, setting the model to auto with no keys entered already gets you an answer, because OmniRoute ships with OpenCode Free, which needs no key, wired in. The README's quick start then suggests connecting Kiro AI or OpenCode Free as your next step.
The same project's free tier document has read each provider's terms and flagged them. These two are flagged avoid. Kiro's FAQ prohibits use through third party tools, and the project notes that OmniRoute falls under that. OpenCode's terms limit use to your own internal use. Since you log in to Kiro with your own account, the risk there lands directly on that account.
The flags you see in the dashboard
| Flag | Meaning | What to do |
|---|---|---|
| ok | The terms explicitly allow this use | Connect it |
| caution | There is a personal use or proxy clause | Read the clause before connecting |
| ambiguous | The terms are unclear | Your call |
| avoid | The terms prohibit or seriously restrict this use | Do not connect it |
The avoid flag does not stop routing
These flags are information only. If you connect a provider flagged avoid, OmniRoute keeps using it in auto and in the fallback order. Nothing blocks it, the decision is yours.
You can see the flags in the dashboard on the Free Tiers page: http://localhost:20128/dashboard/free-tiers. The document is reviewed every two weeks, so both the flags and the free token figures can change. Check there before connecting anything. Right now only a handful of providers get ok, among them Z.AI's free GLM Flash models and DeepSeek's signup credit. The ones you connect with your own API key, like Gemini, Groq and Mistral, are flagged caution.
Tools like Cursor, Codex and Cline speak the OpenAI format and want http://localhost:20128/v1 as the address. Claude Code speaks the Anthropic format and appends /v1 to the address by itself. Give it the address with /v1 and the requests go to the wrong place.
The cleanest route is OmniRoute's own launcher. It writes to no config file and hands the address and model only to the Claude Code session you are opening. Your regular claude command keeps working with your subscription exactly as before.
# Terminal 1: keep OmniRoute running
omniroute
# Terminal 2: open Claude Code through OmniRoute
omniroute run claude --model autoThe second command first checks whether OmniRoute is up. If you closed the first terminal it says OmniRoute is not reachable and does not open Claude Code. It also will not open if Claude Code is not installed on your machine, so install that first.
If you do not want to type the model every time, you can create a separate profile per model. This command writes the profiles under ~/.claude/profiles and does not touch your main settings.json. Profile names are generated from the models you have connected.
omniroute setup-claude
omniroute launch --profile <profile-name>The three most common Claude Code mistakes
Giving it http://localhost:20128/v1 as the address
For Claude Code the address is http://localhost:20128, with no /v1. The /v1 is only for OpenAI format tools
Running the cat > ~/.claude/settings.json command from the docs as is
A single > rewrites the file from scratch, taking your permissions, hooks and plugin settings with it. omniroute run claude touches no file
Changing the setting and testing it in a Claude Code session that is already open
Claude Code reads these settings only when it starts. If you changed them, close it and open it again
For OpenAI format tools three things are enough: the address, the key and the model. You copy the key from the Endpoints page in the dashboard.
Base URL: http://localhost:20128/v1
API Key: copy from Dashboard → Endpoints
Model: autoFor some tools you do not even need to type this in. The omniroute configure codex command shows you the model list and writes Codex's own config, and the same command works for OpenCode, Aider, Goose, Cline, Continue and Kilo. Cursor's settings cannot be written from outside, so omniroute setup-cursor just prints where to click inside the app.
The default memory is not enough for a coding agent
The Docker image ships with a 1 GB memory setting. That is fine for the dashboard and short chats, but once you connect a coding agent like Claude Code or Codex the process crashes with an out of memory error. For a single agent, raise it to 8 GB and give the container at least 10 GB.
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
-e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
-p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latestAn open source AI gateway that points your coding tools at one address and switches to another provider when a limit runs out or something fails. MIT licensed, runs on your own machine, needs no account.
npm install -g omniroute
omnirouteNeeds Node 22.22.2 or above, or 24 through 26. When connecting Claude Code, do not add /v1 to the address; the easiest way is omniroute run claude --model auto.
Installing these tools on your own is one thing; actually building with them is another. The community has people using these daily and people building systems from scratch.
If you want a system that actually runs in your business, let's talk for 10 minutes; I'll look at what you're trying to build and tell you which path fits. Free, and not a sales pitch.
Book a 10-minute callIf you'd rather learn this alongside people doing the same work instead of on your own, the community is always open:
Join the communityThis is an affiliate link.