OmniRoute Setup Guide: Install via npm or Docker & Connect Your Coding Tools

OmniRoute is a self-hosted AI gateway: one OpenAI-compatible endpoint in front of multiple providers, with routing, retries and fallback controls. The official README currently describes 359 providers, 150+ free provider entries and 1,200+ models, but those catalog and free-tier counts change over time. The gateway runs on your own hardware via npm, Docker or a desktop build; upstream providers still receive the requests you route to them.

Step 1Prerequisites

• Node.js + npm — if you install via npm; or
• Docker — if you prefer a container.
• An OpenAI-compatible coding tool you want to route through OmniRoute: Claude Code, Codex, Cursor, Cline, Copilot, Continue, etc.

Step 2Install OmniRoute

Option A — npm (global)

npm install -g omniroute

Option B — Docker

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

This maps port 20128 and persists data in the omniroute-data volume.

Option C — From source

cp .env.example .env && npm install
PORT=20128 npm run dev

Step 3First-run setup & dashboard

Run the guided first-run wizard:

omniroute setup

Then start the gateway + dashboard:

omniroute

By default OmniRoute serves on port 20128:

• Dashboard: http://localhost:20128
• OpenAI-compatible API endpoint: http://localhost:20128/v1

Step 4Connect your coding tool

OmniRoute exposes an OpenAI-compatible endpoint, so any tool that accepts a custom base URL works. In your tool's settings:

• Base URL: http://localhost:20128/v1
• API Key: copy it from Dashboard → Endpoints
• Model: auto for smart routing, or a specific provider/model

Compatible tools include Claude Code, Codex, Cursor, Cline, Copilot and Continue.

Step 5Verify your setup

Diagnose providers, ports and native dependencies:

omniroute doctor

For an interactive chat client in the terminal:

omniroute chat

When OmniRoute fits — and when it does not

Compared with a direct provider SDK, OmniRoute is useful when several tools need one OpenAI-compatible base URL, when you need provider fallback or quota-aware routing, or when you want to change providers without editing every client. A direct provider SDK is simpler when you only use one provider and do not need routing, local credentials or a gateway dashboard.

The trade-off is another local service to operate: provider credentials, model aliases, logs and upstream policy now live in OmniRoute's configuration. Keep DATA_DIR backed up, protect the dashboard and review which upstream receives each request before using it with sensitive data.

Handy CLI commands

OmniRoute ships a command-line cockpit. A few useful ones:

• omniroute — serve gateway + dashboard
• omniroute setup — guided first-run wizard
• omniroute doctor — diagnose providers and ports
• omniroute chat — interactive TUI chat client

Additional command groups referenced in the docs include providers, oauth, keys, models, cache, compression, cost, usage, health, logs, mcp and a2a.

FAQ

How do I install OmniRoute?

npm: npm install -g omniroute; Docker: the docker run … diegosouzapw/omniroute:latest command above; or from source with cp .env.example .env && npm install then PORT=20128 npm run dev.

What port does it use?

20128 by default (dashboard at http://localhost:20128, API at /v1); change it with PORT.

How do I connect my coding tool?

Base URL http://localhost:20128/v1, API key from Dashboard → Endpoints, model auto.

Where is data stored?

DATA_DIR, defaulting to ~/.omniroute; credentials encrypted with AES-256-GCM.

Where are the full docs?

This guide covers install and first connect. For provider-specific setup, advanced commands and options, see the official repo: github.com/diegosouzapw/OmniRoute.

Which release does this guide describe?

The guide was checked against the official v3.8.50 release on 2026-09-22. If your installed version differs, run omniroute --version and follow that version's release notes before copying commands.