Install OmniRoute: Quick Start and Claude Code Setup

OmniRoute is an OpenAI-compatible AI gateway. It puts many upstream model providers behind one local API, so Claude Code, Codex CLI, IDE extensions and your own scripts only need to be configured once. This page is the shortest path from install to a first successful request; the full topic guides live on a dedicated site.

Remember these two addresses

• Dashboard: http://localhost:20128
• OpenAI-compatible Base URL: http://localhost:20128/v1

Clients are configured with the second one, not the dashboard address.

Prerequisites

• Node.js >=22.22.2 <23 or >=24.0.0 <27; Node.js 24 LTS is recommended. Outside that range the dashboard can show a blank page or native-module errors. Install Node.js first if needed.
• Local port 20128 is free.
• At least one upstream provider account or key that you plan to route through OmniRoute.

Install and start

Pick one method:

# npm (recommended)
npm install -g omniroute
omniroute

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

You can also download a Desktop installer for Windows, macOS or Linux from OmniRoute GitHub Releases. :latest points at the newest published stable release; pin an exact version when you need reproducible deployments.

After startup, open http://localhost:20128. The login password is controlled by the INITIAL_PASSWORD environment variable; in the upstream self-hosted setup it is generated on first start and printed to the logs, and with Docker you can find it using docker logs omniroute | grep -i password. Set a strong password of your own before exposing the service to a network.

Connect a provider and create a key

1. In the dashboard, go to Providers → Add Provider and connect your provider.
2. On the API Keys page, create a new key and store it, because it is shown only once. This key is for clients to access OmniRoute, not an upstream provider key.

The upstream docs list some free providers that need no key. Availability and terms change, so check each service’s terms before relying on one.

Verify the service

export OMNIROUTE_API_KEY="paste the key you created on the API Keys page"

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

A model list means the OpenAI-compatible endpoint and authentication both work. Then send a minimal chat request to confirm a model can really be routed:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Reply with ok." }]
  }'

auto lets OmniRoute pick a provider by speed, cost and availability. You can also use a specific model ID returned by /v1/models.

Connect your tools

In any tool that speaks the OpenAI format, enter:

Base URL: http://localhost:20128/v1
API Key:  the OmniRoute key you created
Model:    auto

OmniRoute also ships one-command launchers, for example omniroute launch-codex --model auto; the generic form omniroute run <target> supports claude, codex, aider, goose, opencode, qwen and gemini. If you want to use an Agent CLI inside HagiCode, set it up first with AI Agent CLI Installation.

Common problems

• Blank dashboard or an unsupported Node.js version warning: switch to Node.js 24 LTS, run npm install -g omniroute again, then omniroute.
• better-sqlite3 not found on npm 11: npm 11 blocks install scripts of optional dependencies by default; rebuild it by hand following the troubleshooting guide.
• slice is not valid mach-o file on macOS: run npm rebuild better-sqlite3 inside $(npm root -g)/omniroute/app, then start again.

Full documentation

Open the OmniRoute documentation in English

• Quick Start: Get OmniRoute Running in 3 Minutes
• Configure OmniRoute for Claude Code
• Deploy OmniRoute with Docker
• Configure OmniRoute for Codex CLI
• Troubleshooting