OmniRoute Setup: One Local Endpoint for Every AI Account You Have

One local endpoint that sits in front of every AI account and key you have, and moves you to the next one when a model runs out. Here's the setup, and the parts the reel made sound simpler than they are.

What's actually true today

1 · What it is

OmniRoute is a gateway that runs on your own machine. Every tool talks to one address, http://localhost:20128, and OmniRoute decides which provider actually answers.

• Open source, MIT license: github.com/diegosouzapw/OmniRoute (77,000+ stars, updated this week). The official site is omniroute.online.
• Nothing is hosted for you. Your keys stay on your machine, encrypted.
• Watch for lookalikes. "OmniRouter" and mirror repos are different projects. Install only from the repo above or the omniroute npm package.

2 · Install (5 minutes)

You need Node.js 22.22.2 or newer (or Node 24+). Check with node -v.

npm install -g omniroute
omniroute

Then open localhost:20128 (opens in a new tab). That's the dashboard.

If npm 11 refuses to run install scripts, use the project's own longer command:

npm install -g --allow-scripts=omniroute,keytar,onnxruntime-node,@parcel/watcher,@swc/core,protobufjs,esbuild omniroute

Prefer Docker? This keeps it reachable from your machine only:

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

3 · Connect your providers

In the dashboard, go to Providers and add what you already have:

• API keys (Anthropic, OpenAI, Google, DeepSeek, NVIDIA's free key, and more)
• Subscription accounts you sign into (read the warning in section 7 first)
• Free tiers. The repo has a free-tiers guide. Most need a signup or an API key, and some need a payment method on file.

Then grab your OmniRoute key from Dashboard → Endpoints. Your tools use that key, not your provider keys.

OmniRoute only routes between what you connect. With nothing connected, auto has nowhere to send you.

4 · Pick how it routes

You choose this per request with the model name:

Want it to read your prompt and route simple tasks to cheap models and hard ones to frontier models? That's an opt-in strategy called nadir. It sends your last message to a third-party service (getnadir.com) to decide, and it's off by default.

5 · Point your tools at it

Claude Code

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="your-omniroute-key"
claude

No /v1 on this one. Claude Code adds its own path.

Codex CLI, ~/.codex/config.toml

model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute"
base_url = "http://localhost:20128/v1"
env_key = "OMNIROUTE_API_KEY"
requires_openai_auth = false

export OMNIROUTE_API_KEY="your-omniroute-key"
codex

Anything that speaks OpenAI (Cline, Continue, scripts)

Base URL:  http://localhost:20128/v1
API key:   your-omniroute-key
Model:     auto/cheap

Shortcut

omniroute run claude and omniroute run codex launch the tool with OmniRoute already wired in.

Cursor

OmniRoute's own compatibility table lists the Cursor editor as having no base-URL support and the Cursor CLI as partial. There's an omniroute setup-cursor helper, but don't expect it to work as cleanly as Claude Code or Codex.

6 · How the swap actually works

When a provider hits a quota, rate-limits you, or fails, OmniRoute marks it unhealthy and sends your next request to the next eligible model. That's the "it swaps you without breaking flow" part. Agents send many small requests, so a swap between them is usually all you need.

What it can't do: once an answer is streaming, a swap can't rescue it. If an answer dies halfway through, you re-send it.

It also only works while there's another healthy target to fall back to. One connected provider means nothing to swap to.

7 · Before you trust it with your accounts

• Check the terms before you connect a subscription. A provider's own terms may forbid using your plan through a proxy. OmniRoute marks some providers tos: avoid and keeps them out of auto by default. Don't connect a paid plan you can't afford to lose until you've read its terms.
• Some free providers log everything. The project's free-tiers guide says so outright for at least one. Keep client data off free tiers.
• It holds your keys. They're stored locally and encrypted (AES-256-GCM, per the README). Keep port 20128 on localhost. Don't expose it to the internet without auth.
• It moves fast. The project changes constantly. If an update breaks something, pin the version that worked: npm install -g omniroute@<version>.

The five-minute version

1. 1npm install -g omniroute → omniroute → open localhost:20128.
2. 2Providers: add the keys and free tiers you already have.
3. 3Copy your OmniRoute key from Endpoints.
4. 4Claude Code: ANTHROPIC_BASE_URL=http://localhost:20128 + your OmniRoute key. Everything else: http://localhost:20128/v1.
5. 5Use auto/cheap when you want cheapest-first.

Checked 2026-10-16 against the OmniRoute GitHub repo and README (release v3.8.51), its docs on CLI tools, auto-routing, free tiers and resilience, the npm package, and omniroute.online. Install steps are from the official docs and were not run on this machine. Provider and model counts change with every release.