How to Use OmniRoute, the Free AI Gateway

In short: OmniRoute is a free, open-source (MIT) AI gateway that runs on your own computer. You connect the AI providers you have accounts or API keys for, and OmniRoute gives your coding tools one endpoint, http://localhost:20128/v1, that routes each request to a connected provider and falls back to another when one hits its limit. OmniRoute does not hand out tokens itself: the free usage comes from the providers' own free tiers.

What you need

• Node.js and npm, or Docker.
• At least one AI provider account or API key. Free options with daily limits are listed in how to get AI API keys for free, for example an OpenRouter key or a Gemini key.
• A coding tool that accepts an OpenAI-compatible base URL, such as Claude Code, Codex CLI, Cline, Kilo Code, OpenCode, Aider or Continue.

How the free usage works

The README puts the combined free tiers at about 1.62B tokens a month, and states plainly that this is "an estimated aggregate across separately eligible third-party free tiers, not a token grant from OmniRoute". You only get the parts whose providers you sign up for and connect, and each provider sets its own limits and terms. Read on 30 October 2026:

The dashboard's Free tiers page (/dashboard/free-tiers) shows what is used and left for the providers you connected.

Step 1: Install OmniRoute from npm and start it

Open a terminal and run (box 1):

npm install -g omniroute
omniroute

The dashboard opens at http://localhost:20128 and the API is at http://localhost:20128/v1. Run omniroute setup instead for a guided first-run wizard.

Two install notes from the README:

• npm warn ERESOLVE and peer-dependency warnings are harmless.
• npm 11 or later may block install scripts that OmniRoute needs. Allow the packages npm names in its warning, with npm install -g --allow-scripts=<names from the warning> omniroute.

With Docker instead of npm:

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

The Docker image is set to 1 GB of memory, which the README sizes for the dashboard and light chat. For a coding agent it gives -e OMNIROUTE_MEMORY_MB=8192 --memory=10g.

Step 2: Connect a provider

In the dashboard, open Providers (box 1 below), choose a provider, and add its API key or complete its account sign-in. Some free tiers need a sign-up, an approval or a payment method; the Free Tiers Guide lists each one. Your keys stay on your computer, stored encrypted.

Step 3: Use OmniRoute with Claude Code, Codex or OpenCode

Copy your OmniRoute API key from Dashboard → Endpoints, then set these three values in your tool (box 2):

auto picks among your connected providers. Variants change what it favours:

For supported CLIs, OmniRoute can launch the tool with the settings filled in, for example omniroute run claude --model glm/glm-5.2 or omniroute run opencode --model glm/glm-5.2. omniroute configure codex writes the tool's own config file instead.

Step 4: Check that it works

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

Replace YOUR_KEY with your OmniRoute key. The answer lists the models of the providers you connected. A first chat request:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

When something goes wrong

Words to know

• Gateway: one API that passes your request on to many model providers.
• Endpoint: the address a tool sends its requests to, here http://localhost:20128/v1.
• Fallback: when one provider fails or hits its limit, the request goes to the next one.
• API key: the password that identifies your program to an API. See what is an API key.

More free AI

A free coding agent with its own daily allowance: how to use OmniRush. Free API keys with daily limits: how to get AI API keys for free. Free models for coding tools: free AI API for coding.