📊 See OmniRoute rankings

📱 Get the AI Rank app

OmniRoute is a self-hosted AI gateway. You run it on your own machine or server, connect the provider accounts and API keys you already have, and point your coding tools at one local endpoint, http://localhost:20128/v1. When a provider hits a rate limit, runs out of quota or fails, OmniRoute moves the request to the next eligible provider. The project is MIT-licensed and lives at diegosouzapw/OmniRoute.

An OmniRoute Claude Code setup is one of the documented paths. Claude Code speaks the Anthropic Messages API, and OmniRoute ships a launcher and a settings.json fragment for it. Codex CLI gets its own launcher and a ready-made config.toml block.

On AI Rank, OmniRoute sits in the Infrastructure category (Observability, Gateway). It ranked #31 among all tracked repos on the Oct 16, 2026 daily snapshot and #42 on Oct 19, with 77,885 stars.

How OmniRoute Routes Requests

The endpoint at /v1 accepts OpenAI-style requests, and the README also lists Claude, Gemini and Responses API compatibility there. Each request goes to a model you name, such as openai/gpt-4o, or to a combo, which is a chain of models OmniRoute walks through when one fails.

You don't have to build a combo. Set the model to auto and OmniRoute builds one from your connected providers. The README lists variants:

Model ID What it favors
auto Balanced default that sticks to your last good provider
auto/coding Quality-first weights for code generation
auto/fast Lowest latency
auto/cheap Lowest price per token
auto/subscription Only subscription quota you already pay for; never falls back to a billable route

Failover runs on three layers, per the README: a circuit breaker per provider that trips on 408 and 5xx errors, a cooldown per key or account that honors Retry-After on 429, and a lockout per model for model-specific errors. The README counts 20 routing strategies for custom combos.

Credentials are encrypted at rest with AES-256-GCM, and telemetry is off by default. Prompts still go to whichever upstream provider handles each request.

Install OmniRoute

The npm package is omniroute. The latest published release is 3.8.51 (Sep 30, 2026). It needs Node.js 22.22.2 or later on the 22 line, or 24.x through 26.x.

npm install -g omniroute
omniroute

The dashboard opens at http://localhost:20128 and the API is at http://localhost:20128/v1. Docker is the other documented route:

docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

omniroute doctor checks providers, ports and native dependencies after install.

Configuration

Setup has three steps, all in the dashboard:

  1. Connect a provider. Under Dashboard → Providers, add an API key or sign in to an account, then test the connection.
  2. Create an OmniRoute key. Under API Keys, create a key and store it; it is shown once. This key lets your tools reach OmniRoute. It is not an upstream provider key.
  3. Point your tool at it. Use base URL http://localhost:20128/v1, your OmniRoute key, and model auto or a specific provider/model.

Check that routing works by listing models:

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

Requests then show up under Monitoring → Logs in the dashboard.

OmniRoute Claude Code Setup

Claude Code has no --base-url flag. It reads environment variables at startup, so restart it after any change. The quickest route is OmniRoute's launcher, which sets them, health-checks the server and starts claude:

omniroute launch

To configure Claude Code yourself, the dashboard's CLI Code card shows a settings.json block like this one, for a local instance. Paste your key over the placeholder:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

ANTHROPIC_BASE_URL takes the server root with no /v1, because Claude Code adds /v1/messages itself. omniroute setup-claude writes one profile per model under ~/.claude/profiles/<name>/settings.json, and omniroute launch --profile <name> starts Claude Code with one of them.

Claude Code's /model picker only lists IDs that start with claude or anthropic. To show other models there, turn on OmniRoute's discovery aliases (off by default) under Settings → Feature Flags → EXPOSE_CC_DISCOVERY_ALIASES, or per provider or model. A model such as glm/glm-5.2 then appears as claude/glm/glm-5.2.

Codex CLI Setup

The Quick Start keeps the key in an environment variable and launches Codex through OmniRoute:

export OMNIROUTE_API_KEY="<YOUR_KEY>"
omniroute launch-codex --model auto

For a permanent setup, Codex reads only ~/.codex/config.toml; the old config.yaml is ignored. The provider block from the Codex guide:

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://<YOUR_HOST>:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

Set model_provider = "omniroute" at the top of the file. omniroute setup-codex generates profiles per model, and omniroute configure codex picks a model interactively and writes the config for you.

OmniRoute vs LiteLLM and OpenRouter

OmniRoute's repo has its own comparison page, audited in 2026-Q2. It is the project's view of its competitors, so treat the feature rows as claims. The table below keeps the rows that are easy to check:

OmniRoute LiteLLM OpenRouter
Self-hosted Yes Yes No (hosted service)
License MIT MIT Proprietary
Fallback 20 combo strategies Priority-based Tier-based
Built-in MCP server Yes No No

The same page suggests LiteLLM for Python-first teams that want litellm.completion() and mature Kubernetes or Helm recipes. It suggests OpenRouter for people who don't want to self-host and want one payment method across providers. OmniRoute's provider counts vary across its own docs (329 in the comparison table, 375 in the README), so don't lean on the exact number.

Common Pitfalls

  • npm blocks install scripts. npm 11 and later can block lifecycle scripts. OmniRoute's postinstall copies the native SQLite driver into place; without it, OmniRoute falls back to slower drivers. Allow the packages named in npm's warning with --allow-scripts. The README and the troubleshooting guide give different lists (the guide says to leave out onnxruntime-node, a roughly 300 MB optional download), so go by the warning you actually see.
  • Node.js version. Versions outside 22.22.2+ on the 22 line or 24 to 26 can break the login page with a "Module did not self-register" error. Install Node.js 24, reinstall, and restart.
  • auto has nothing to route to. A fresh install may have no eligible provider. Providers marked tos: avoid, including Kiro, stay out of auto even after you connect them.
  • Wrong Claude Code URL. Adding /v1 to ANTHROPIC_BASE_URL breaks Claude Code, which appends /v1/messages on its own.
  • Context window mismatch. Claude Code assumes a 200K window for model IDs it doesn't know. For larger models, set CLAUDE_CODE_AUTO_COMPACT_WINDOW below the real window. Profiles from setup-claude already do this.
  • Free tiers return 429, 400 or 401. The troubleshooting guide suggests OMNIROUTE_ROTATE_ON_400=true in the OmniRoute process environment, plus a second account when quota is truly exhausted.
  • omniroute not found on Windows. Add the npm global prefix (npm config get prefix) to PATH.

FAQ

Is OmniRoute free? The software is free under the MIT license. You pay the providers you route to, and their free tiers come with their own terms and limits.

Which key goes where? Your tools send an OmniRoute API key created in the dashboard. Provider API keys and account logins stay inside OmniRoute.

Can it run on a server instead of my laptop? Yes. omniroute connect <host> logs the local CLI in to a remote instance with a scoped token, and omniroute launch --remote points Claude Code at it.

Does it work with Cursor? The README lists Cursor CLI among supported tools and says any OpenAI-compatible tool can use the /v1 endpoint.

Keep exploring: see which open-source AI projects are rising today in the open-source rankings on AI Rank.

Or 📱 get the AI Rank app to follow them on your phone.

Sources

Prepared with automated editorial assistance and checked on October 19, 2026 against the OmniRoute repository and docs, the npm registry and dated AI Rank snapshots. OmniRoute was not installed or tested.

Cover image: official product imagery; editorial composition by AI Rank.