OmniRoute Explained: Setup With Claude Code and Codex, Security, Provider Terms and Alternatives

OmniRoute is a free, MIT-licensed AI gateway that runs on your own machine. It gives coding tools such as Claude Code, Codex, OpenCode and Hermes Agent one endpoint, http://localhost:20128/v1, and routes each request across the subscriptions, API keys, free tiers and local models you connect, moving on when one runs out or fails. The current release is v3.8.52, published on 19 October 2026.

The project appeared on GitHub on 13 February 2026 and passed 84,000 stars by 4 November 2026. This guide draws on its README, docs, source code, releases and advisory, and on each provider’s terms, all read that day. Choosing a gateway for a company rather than one developer? Start with our comparison of hosted and self-hosted LLM gateways.

What is OmniRoute?

OmniRoute is a gateway, not a model or an agent. One Node.js process serves a web dashboard and an API on port 20128. Your tools call that port; OmniRoute picks a connected provider, converts between the OpenAI, Anthropic and Gemini formats where needed and sends the request from your machine. The README says no hosted service sits in between and that telemetry is off by default.

Unlike general-purpose LLM gateways, it treats coding subscriptions such as Claude, ChatGPT, GitHub Copilot and Kimi Code as providers, catalogues free tiers and adds agent tooling: setup commands for over a dozen coding tools, compression for long tool output and a 110-tool MCP server. The project was created by Diego Souza and has since joined Cheaper Inference, which sells hosted, cost-ranked model access. Its website says the self-hosted gateway still routes only to the providers you connect, at their own prices.

How OmniRoute routes requests

The README draws routing as a four-tier cascade, set on the dashboard’s Tiers page. A request moves down only while a healthy, eligible target remains.

Combos are named chains of models, each step using one of 20 strategies, from priority order and round robin to cost-optimised and quota-aware choices, plus fusion, where a judge merges a panel’s answers, and pipeline, where one model’s output feeds the next.

The auto model builds a virtual combo from your connections and scores candidates on 16 factors, including health, quota, cost and latency. auto/coding, auto/fast and auto/cheap shift the weights, and auto/subscription stays on plan quota and fails rather than spend money.

Circuit breakers per provider, cooldowns per key and lockouts per model handle errors, and an X-OmniRoute-Decision header names the provider behind each response. The same principle lowers an organisation’s inference bill when requests are routed by task; OmniRoute applies it to one person’s quotas.

How to install OmniRoute

It needs Node.js 22.22.2 or later 22.x, or 24 to 26.

1. Install and start the server:

   npm install -g omniroute
   omniroute

   npm 11 may block the install scripts OmniRoute needs; the README lists the packages to allow with --allow-scripts.

2. Open http://localhost:20128 and set the dashboard password. omniroute setup is a guided first-run wizard for the terminal, and omniroute doctor checks ports and native dependencies.

3. Under Providers, connect an API key or an account.

4. Copy your key from Dashboard > Endpoints and test it:

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

Install globally or just locally?

Once per machine. The README documents global installs (npm, bun add -g omniroute, pnpm), npx -y omniroute and Docker, but no per-project install. OmniRoute is one server on one port, and its database and stored credentials live in a single data directory, ~/.omniroute by default on macOS and Linux. For isolation, run the image pinned and published on localhost only:

docker run -d --name omniroute --restart unless-stopped \
  -e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data \
  diegosouzapw/omniroute:3.8.52

The image’s default 1 GB heap suits the dashboard and light chat; the README recommends 8 GB, in a container of at least 10 GB, for one coding agent.

OmniRoute download: desktop apps

The v3.8.52 GitHub release has Electron builds for Windows, macOS (Intel and Apple silicon) and Linux (AppImage and .deb for x64 and ARM64), roughly 300 to 720 MB each. Download them from the main repository only.

How to use OmniRoute with Claude Code

Claude Code reads its endpoint from environment variables, so no plugin is needed and the project ships none. The OmniRoute skills that appear in searches are the 45 agent skills documented in its repository: SKILL.md files that teach an agent to drive OmniRoute’s CLI and API.

• One command: omniroute launch sets ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN for that process and starts claude.

• Profiles: omniroute setup-claude --dry-run previews, and omniroute setup-claude writes, one profile per model under ~/.claude/profiles/; omniroute launch --profile <name> injects the token at start.

• By hand: add an env block to ~/.claude/settings.json:

  {
    "env": {
      "ANTHROPIC_BASE_URL": "http://localhost:20128",
      "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
      "ANTHROPIC_MODEL": "<provider/model or combo name>"
    }
  }

Leave /v1 off the base URL, because Claude Code appends /v1/messages. Its /model picker shows gateway models only with CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, and then only IDs that start with claude or anthropic. It also assumes a 200K-token window for IDs it does not know, which CLAUDE_CODE_AUTO_COMPACT_WINDOW corrects.

Anthropic accepts any gateway that exposes a supported API format but neither endorses nor audits them, and it does not support routing Claude Code to non-Claude models. While a gateway credential is set, your claude.ai plan limits stop applying and billing follows the upstream credential. For Claude Code on a local model alone, a gateway is optional; see our guide to Claude Code with Ollama, LM Studio or llama.cpp.

OmniRoute with Codex, OpenCode, Hermes Agent and VS Code

Codex

omniroute run codex --model <provider/model> starts Codex through the gateway without editing files, and omniroute setup-codex writes the configuration. By hand, OmniRoute’s guide uses the Responses wire format in ~/.codex/config.toml:

model = "auto"
model_provider = "omniroute"

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

Our walkthrough of Codex with local models covers its other provider settings.

OpenCode

omniroute setup-opencode, with --dry-run to preview, adds a standard OpenAI-compatible provider to OpenCode’s config:

{
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "{env:OMNIROUTE_API_KEY}"
      },
      "models": { "auto": { "name": "OmniRoute auto" } }
    }
  },
  "model": "omniroute/auto"
}

Our OpenCode configuration guide covers permissions and keeping code on your machine.

Hermes Agent

Run hermes model, choose the custom endpoint and enter http://localhost:20128/v1 with your OmniRoute key, or set provider: custom, base_url and api_key under model: in ~/.hermes/config.yaml. OmniRoute’s dashboard can also write that file, with a model per Hermes role. Hermes rejects models with less than 64,000 tokens of context, so route it to large-window models rather than leaving the choice to auto. Our comparison of Hermes Agent with Claude Code and OpenCode explains the differences.

VS Code

OmniCopilot, an MIT-licensed extension published by diegosouzapw (version 1.3.0), adds OmniRoute’s models to the Copilot Chat model picker in VS Code 1.104 or newer, and is on Open VSX for VS Code forks. Since VS Code 1.122, released on 28 May 2026, such models work without a GitHub sign-in, though inline suggestions still need Copilot. Cline, Continue, Kilo Code and Roo Code can use http://localhost:20128/v1 directly. Avoid OmniRoute’s tokenised URLs, which carry the key in the path, where logs keep it.

Running OmniRoute with local models

OmniRoute forwards to model servers rather than running models. The v3.8.52 list has 14 local providers, each configured by base URL:

• Current llama-server builds default to port 9931, so pass --port 8080 or change the URL.
• From Docker, OmniRoute’s guide reaches Ollama on the host at http://host.docker.internal:11434/v1.
• Since v3.8.51, local and LAN targets get 300 seconds to send a first byte instead of 30.

auto draws on every connected provider. On a machine whose code must stay local, connect local providers only, or point your tools at a combo that lists only local models. For the model, pick one with reliable tool calling from our shortlist of open-weight coding models.

Is OmniRoute safe? Security settings to change

OmniRoute holds the keys and tokens of every account you connect and sees every prompt, so treat it like a password manager that also relays traffic.

1. Network exposure. In v3.8.52, omniroute serve binds to all interfaces unless OMNIROUTE_SERVER_HOST is set, and /v1 needs no key unless REQUIRE_API_KEY=true; the server prints a warning at startup when both defaults apply. Set both on the command line or in the data directory’s .env file:

   OMNIROUTE_SERVER_HOST=127.0.0.1 REQUIRE_API_KEY=true omniroute serve

   The key requirement does not cover GET /v1/models.

2. Dashboard password. The environment reference says npm and source installs start with the public placeholder CHANGEME as INITIAL_PASSWORD. Replace it before the first start, or set a password in the onboarding wizard.

3. Stored credentials. Keys and OAuth tokens sit in SQLite in the data directory, encrypted with AES-256-GCM, but the encryption key is generated into server.env in the same folder. Protect the whole folder as a secret.

4. Known vulnerability. Advisory GHSA-hf57-cqmx-p4gr (CVE-2026-88062, critical) describes arbitrary code execution through the endpoint that registers custom ACP agents, without authentication when login was off or before a management password existed. The project lists 3.8.49 as fixed, while GitHub’s reviewed entry lists versions up to 3.8.50 as affected. The fix, pull request #11028 of 21 August 2026, also closed SSRF and authorisation-bypass reports. Run 3.8.52 or later and keep login on.

5. MCP control. The built-in MCP server’s 110 tools can change providers, keys and routing, and its scope checks are opt-in, so connecting it hands an agent the gateway’s controls.

6. Trust store. Optional MITM and TPROXY modes install a certificate authority to decrypt traffic from tools that ignore proxy settings; leave them off unless needed.

7. The right package. The repository has over 12,000 forks, and npm lists more than a dozen other publishers’ packages named after OmniRoute. Use the omniroute or @omniroute/ packages, the diegosouzapw/omniroute image or the main repository’s releases; the 3.8.52 npm package has a provenance attestation tied to the project’s publishing workflow.

Can you route a Claude, ChatGPT or Gemini subscription through OmniRoute?

Tier 1 is where OmniRoute meets the providers’ terms. The project tells users to respect them and not to open extra accounts to get around quotas, and it keeps providers marked tos: avoid, Kiro among them, out of auto by default. What the largest providers say:

• Anthropic. Claude Code’s legal page says subscription OAuth is designed for ordinary use of Claude Code and Anthropic’s native apps. It bars third-party developers from routing requests through Free, Pro, Max or Ultra credentials for their users, or from collecting, storing or intermediating Claude.ai tokens, and Anthropic may enforce this without notice; the consumer terms forbid sharing an account. OmniRoute’s notes on its Claude provider say it rewrites other clients’ requests to present as Claude Code, because Anthropic otherwise rejects them with a message that third-party apps draw from extra usage, not plan limits. An Anthropic API key upstream is the route Anthropic describes for developers.
• OpenAI. The Codex docs offer ChatGPT or API-key sign-in, say the cached ChatGPT login holds access tokens to be treated like a password, and recommend API keys for programmatic workflows. OpenAI’s separate Sign in with ChatGPT programme lets open-source and local personal projects use a plan through OpenAI’s own registration flow. A gateway holding your Codex login is a different arrangement; check with OpenAI first.
• Google. The Gemini CLI terms, updated on 10 April 2026, call access to the services behind Gemini CLI through third-party software a violation that may lead to suspension or termination, and clause 6 of the Antigravity terms says the same. OmniRoute dropped its Gemini CLI connection after Google replaced Gemini CLI with Antigravity CLI for unpaid and Google One users on 18 June 2026, but still offers Antigravity sign-in.

Check the site terms behind the 37 web-session connections too, which reuse browser logins from ChatGPT, Claude, Gemini and others. These terms bind the account holder, not the software. For company work, API keys under commercial terms avoid the question.

OmniRoute vs OpenRouter vs LiteLLM vs 9router

Rows use each project’s own documentation, read on 4 November 2026:

OmniRoute vs OpenRouter. OpenRouter adds no markup to model prices, charges fees on credit purchases and on large bring-your-own-key volumes, and can route only to providers that retain no data, but your prompts pass through it. OmniRoute calls providers directly from your machine and can use OpenRouter as one of them.

OmniRoute vs LiteLLM. LiteLLM governs API-key access for many applications and teams; OmniRoute is organised around one developer’s subscriptions and free tiers. Teams should start with our review of LiteLLM’s alternatives.

OmniRoute vs 9router and FreeLLMAPI. OmniRoute’s README says it began as a fork of decolua’s 9router and a TypeScript port of the Go project CLIProxyAPI; 9router keeps the tiered design and port 20128 with a smaller catalogue. FreeLLMAPI pools free API keys rather than subscription logins, and its README says provider terms still apply to proxied traffic.

OmniRoute vs Ollama and OpenCode. Different layers: Ollama runs models, while OpenCode, Claude Code, Codex and DeepSeek’s own harness are agent harnesses that call them. OpenCode can call OmniRoute, and OmniRoute can forward to Ollama.

Which one should you use?

• Solo, with several subscriptions or free tiers: OmniRoute or 9router on 127.0.0.1 with a key, after reading the terms above.
• One bill and nothing to run: OpenRouter.
• Shared infrastructure for many teams: LiteLLM or another team gateway.
• A coding agent on a local model: no gateway; point the agent at Ollama, LM Studio or llama.cpp.
• Approved models, an audit trail and on-premises routing: see below.

How VDF AI fits

OmniRoute decides which of one person’s subscriptions and free quotas receives their code. An organisation starts from the other end: which models may see which data, a record of every call, and proof that requests stayed inside its network. VDF AI does not run, host or integrate with OmniRoute.

VDF AI Router covers that case. It runs on your own VMs, Kubernetes or bare metal, applies allow and deny lists and regulated-domain approvals before any call, and registers on-premises endpoints such as vLLM or Ollama beside approved cloud models, which it reaches through OpenRouter. Air-gap mode keeps routing on local models, and each decision returns its reason and fallback candidates for the audit trail. It documents a REST API and a Python SDK rather than an OpenAI-compatible endpoint, so applications integrate it instead of coding tools pointing at it.

For engineering teams, VDF Code is the governed coding assistant on infrastructure you control. It shares the platform with governed agents, Networks for multi-agent orchestration and private RAG over company documents; every plan includes role-based access control and audit logs.