OmniRoute Setup Guide

From npm install to your first free AI request — every step with copy-paste commands.

Step 1 — Install OmniRoute

OmniRoute installs in one command. Pick the method that matches your machine — npm is the fastest path on macOS, Linux, and Windows.

npm (recommended)

npm install -g omniroute
omniroute

Requires Node 18+. Dashboard opens at localhost:20128.

Docker

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

Best for servers and NAS. Data persists in the omniroute-data volume.

pnpm

pnpm add -g omniroute@latest \
  --allow-build=better-sqlite3 --allow-build=@swc/core
omniroute

Same as npm but with pnpm's build permission flags.

Arch Linux (AUR)

yay -S omniroute-bin
systemctl --user enable --now omniroute.service

Runs as a user service, starts on login.

After launch, the OmniRoute dashboard is at http://localhost:20128 and the OpenAI-compatible API at http://localhost:20128/v1.

Step 2 — Connect a Free Provider

Open the dashboard and go to Providers. For a $0 start, connect one of these two:

Kiro AI

Free Claude access with roughly 50 credits per month per account. Sign in with OAuth from the OmniRoute dashboard — no API key to manage.

OpenCode Free

No auth at all. Enable it and it works immediately — the fastest way to verify your OmniRoute install end to end.

Want more free capacity? The OmniRoute free providers list covers all 90+ free tiers with auth requirements for each.

Step 3 — Point Your Coding Tool at OmniRoute

Every OpenAI-compatible tool connects the same way. Copy the API key from Dashboard → Endpoints first.

Base URL: http://localhost:20128/v1
API Key: [from Dashboard → Endpoints]
Model: auto # zero-config smart routing

Tools that work with OmniRoute

Claude CodeCodex CLICursorClineGitHub CopilotAntigravityWindsurfRoo CodeAiderOpenCodeContinueZedVS Code (generic OpenAI)JetBrains AI

OmniRoute translates between OpenAI, Claude, Gemini, and Responses API formats automatically — so an Anthropic-native tool like Claude Code and an OpenAI-native tool like Cursor both work against the same endpoint.

Step 4 — Verify Everything Works

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

If the response lists your connected models, OmniRoute is routing correctly. Set your model to auto and start coding — OmniRoute handles fallback, quota tracking, and compression from here.

OmniRoute Setup FAQ

What are the system requirements for OmniRoute?
Node.js 18 or newer for the npm install, or Docker for the container route. It runs on macOS, Linux, Windows, and ARM devices like a Raspberry Pi or NAS.
Which port does OmniRoute use?
By default OmniRoute listens on port 20128 — the dashboard at http://localhost:20128 and the OpenAI-compatible API at http://localhost:20128/v1. You can change it with the PORT environment variable.
How do I connect Claude Code to OmniRoute?
Set the Anthropic base URL to your OmniRoute endpoint and use the API key from Dashboard → Endpoints. OmniRoute translates between OpenAI, Claude, and Gemini API formats automatically.
The npm install fails on better-sqlite3 — what do I do?
The native SQLite engine is optional. OmniRoute falls back to a pure-JS engine (node:sqlite on Node 22+, else bundled sql.js WASM) automatically, so the install never blocks on compilation.
Can I run OmniRoute on a server instead of my laptop?
Yes. The Docker image with a volume for /app/data is the recommended server setup. The docs cover Compose profiles, Caddy HTTPS, and Cloudflare tunnels for remote access.
What model name should I use in my coding tool?
Start with auto — OmniRoute builds a virtual combo from your connected providers and scores them live. Variants like auto/coding, auto/cheap, and auto/fast optimize for quality, cost, or latency.

Next Steps

Browse Free Providers OmniRoute vs OpenRouter