OmniRoute

1. What is OmniRoute?

OmniRoute is an AI "relay" that runs on your own computer. Instead of configuring every AI tool separately with every model provider (OpenAI, Anthropic, Google, DeepSeek...), you point them all at a single address on your machine, and OmniRoute passes each request to a suitable provider. When one provider runs out of quota or fails, it switches to another that still works. It also trims the content it sends to save tokens (the unit AI models charge by).

It is free and open source under the MIT license. The README says it connects to more than 350 providers, of which more than 150 have a free tier. OmniRoute itself does not sell AI models: free or paid plans belong to each provider, and the project states plainly that free-tier figures change over time.

Plainly: OmniRoute is mainly for people who use AI coding tools such as Claude Code, Codex, Cursor or Cline. It has a fairly friendly browser dashboard and a desktop app version, but its value only shows when you have an AI tool to connect to it.

A good fit if:

• You use AI coding tools and keep getting blocked when a quota runs out mid-task.
• You want to make use of several providers' free tiers from one place.
• You want to see how many tokens, and how much money, you are spending.

Not a fit if:

• You only want an AI chat app for everyday questions. Using a chat app directly is much simpler.
• You do not use any tool that has "Base URL" and "API Key" settings.
• You are short on disk space: the desktop installer files run from about 300 MB to about 680 MB depending on the system.

2. What you need

It depends on the install route you pick in section 3:

• Route 1, desktop app: nothing to install first. You need Windows, macOS or Linux and roughly 300 to 680 MB free to download the installer (about 580 MB on Windows, 670 MB on macOS, 310 to 430 MB on Linux).
• Route 2, command line: you need Node.js, the software that runs tools written in JavaScript. OmniRoute requires version 22.22.2 or later on the 22 line, or version 24 and above (below 27); the project recommends Node.js 24 LTS. Download from https://nodejs.org
• Route 3, Docker: you need Docker, a tool that runs software in ready-made packaged "boxes". Download from https://www.docker.com
• Android phone: it runs through the Termux app (a command-line window for Android). This route is for people already comfortable with it; see the dedicated guide at https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/TERMUX_GUIDE.md

About accounts: a fresh install can already answer without any API key or sign-up, thanks to a free provider that needs no login and comes pre-connected. To use stronger models you connect accounts or API keys from other providers; whatever costs money is set by those providers.

3. Step-by-step installation

Step 1 (easiest): Download the desktop app

Open the official releases page:

https://github.com/diegosouzapw/OmniRoute/releases

On the newest release (at the time of writing v3.8.51, published 30 September 2026), scroll to Assets and download the file that fits your machine:

System	File to download
Windows (installer)	OmniRoute.Setup.3.8.51.exe
Windows (run directly, no install)	OmniRoute.exe
macOS, Apple Silicon	OmniRoute-3.8.51-arm64.dmg
macOS, Intel	OmniRoute-3.8.51.dmg
Linux	OmniRoute-3.8.51.AppImage or a .deb file

The version number in the file name changes with newer releases.

Step 2: Install and open the app

Windows: run the OmniRoute.Setup…exe file, follow the steps, then open OmniRoute from the Start menu or the desktop icon.

Note: the project says the Windows installer is not code-signed yet, so some antivirus programs (the documentation names Kaspersky) may flag it by mistake and remove the install. Download only from the official Releases page above. The fix is in section 5.

macOS: open the .dmg, drag OmniRoute.app into the Applications folder and open it from there. The app is not signed with an Apple certificate; if macOS blocks it, right-click the app, choose Open, then Open again. Or run this command:

xattr -cr /Applications/OmniRoute.app

Linux: make the AppImage executable, then run it:

chmod +x OmniRoute-*.AppImage
./OmniRoute-*.AppImage

What success looks like: the OmniRoute window shows the dashboard, and an OmniRoute icon sits in the system tray. The app runs its internal server on port 20128 by itself.

Route 2: Install from the command line (npm)

Check Node.js first:

node --version

The number printed must be on the 22 line (22.22.2 or later) or 24 and above. Then:

npm install -g omniroute
omniroute

The first line downloads and installs; the second starts it. During installation you may see many npm warn lines; the project confirms they are harmless as long as you finally see an added … packages line.

What success looks like: your browser opens the dashboard at http://localhost:20128. Keep that command window open; closing it stops OmniRoute.

Route 3: Run with Docker

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

Then open http://localhost:20128 in your browser. By default the Docker version gives OmniRoute only 1024 MB of memory, enough for the dashboard and light chat. If you connect AI coding tools, the documentation advises raising it according to the table in the Docker Guide: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md

4. First use

Step 1: Connect a free provider

In the dashboard, open Providers. The README suggests two no-cost options to begin with:

• OpenCode Free: no login needed.
• Kiro AI: gives free access to Claude, about 50 credits a month per account.

Click connect and follow the on-screen instructions. What success looks like: the provider shows as connected.

Step 2: Get OmniRoute's API key

Open Endpoints, create an API key and copy it. This key is issued by the OmniRoute on your own machine so that other tools can call it; it is not a key from OpenAI or any other company.

Step 3: Point your AI tool at OmniRoute

In your tool's settings (Cursor, Cline, Continue... or any tool that speaks the OpenAI standard), fill in three fields:

Base URL: http://localhost:20128/v1
API Key:  (the key you copied in Endpoints)
Model:    auto

The model name auto means OmniRoute picks the best provider that is currently usable.

If you installed from the command line and use Claude Code or Codex, you can launch the tool through OmniRoute with one command. The README's example:

omniroute run claude --model openai/gpt-5.4

Step 4: Check that it works

Replace YOUR_KEY with your key and run this (in Windows PowerShell, type curl.exe instead of curl):

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

What success looks like: you receive a list of the models you have connected. From here, send a question in your AI tool; the answer travels through OmniRoute and the usage appears on the dashboard. Remaining free quota can be seen on the /dashboard/free-tiers page.

5. Common problems and fixes

Symptom	Cause	Fix
The AI tool says it cannot connect	OmniRoute is not running	Open the app, or run omniroute; with Docker: docker restart omniroute
Windows says omniroute is not recognized	The global npm folder is not on PATH	Run npm config get prefix to see the path, then add that path to Windows PATH
Blank login page or a "Module did not self-register" error	The Node.js version is outside the supported range	Install Node.js 24 LTS, run npm install -g omniroute again, then omniroute
You cannot log in to the dashboard	No admin password set yet, or forgotten	Run omniroute setup to set a password and the first provider; if forgotten, omniroute reset-password. You can also set the INITIAL_PASSWORD environment variable for the first login
"Rate limit exceeded" or 429	Too many requests to one free provider	Wait about a minute, use the auto model, or connect more providers
"Quota exceeded"	That account's quota is used up	Connect another provider or add a second account
401 or "Invalid API key"	The key is wrong or expired	Copy the key again from Endpoints; for a provider, sign in again or get a new key
Kaspersky reports a Trojan and removes the app on Windows	A false alarm caused by the unsigned installer	Compare the file's sha512 with latest.yml on the Releases page, restore the files, add an exception for the %LOCALAPPDATA%\Programs\OmniRoute folder, then reinstall
Avast or AVG quarantines OmniRoute's README.md	A false alarm on a text file with many links	Restore the file and add an exception; nothing more is needed
EACCES: permission denied	It cannot write to the data folder	Set the DATA_DIR environment variable to a folder you can write to
macOS shows dlopen … slice is not valid mach-o file	A native component does not match your machine	Run the commands below

The fix for the dlopen error on macOS:

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

If another program is already using port 20128, start on a different port (remember to change the port in the Base URL to match):

omniroute --port 3000

When you cannot tell where the problem is, run omniroute doctor to check the data folder, database, providers and ports. Full list of problems: https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/TROUBLESHOOTING.md

6. Uninstalling and updating

Updating

• Command-line version: run omniroute update to check for and apply a new version.
• Desktop app: download the latest installer from the Releases page and install it over the old one.
• Docker: the :latest tag points to the newest stable release; how to replace the container is in the Docker Guide.

Uninstalling

Desktop app on Windows: open Settings, Apps, find OmniRoute and choose Uninstall.

Desktop app on macOS and Linux: drag OmniRoute.app from Applications to the Trash (macOS), or delete the AppImage file (Linux). The data lives in its own folder, described just below.

Command-line version (npm):

npm uninstall -g omniroute

Docker:

docker stop omniroute
docker rm omniroute
docker volume rm omniroute-data

The last line deletes all data.

OmniRoute's data (providers, keys, usage history) lives by default in ~/.omniroute/ on macOS and Linux, and in %APPDATA%\omniroute on Windows (if you have set the DATA_DIR or XDG_CONFIG_HOME variable, it is there instead). Uninstalling the program does not remove this folder. Keep it if you plan to reinstall; delete it if you want a clean removal, for example on macOS and Linux:

rm -rf ~/.omniroute

Note: deleting the data folder loses all provider connections, API keys and history, and it cannot be recovered.

7. Frequently asked questions

Does OmniRoute cost anything? OmniRoute is free. Any cost comes from the model providers you connect. You can start entirely on free tiers, but they have limits and can change.

Does it need the internet? Yes. OmniRoute runs on your machine but the AI models sit on the providers' servers, unless you connect it to a model running locally.

Is my data sent anywhere? According to the README: the gateway and dashboard run on your machine; request content goes to the provider selected for that request, with no extra OmniRoute server in between; usage telemetry is off by default; keys and credentials are encrypted when stored. The provider that receives a request handles it under its own policy.

Will it run on a weak machine? The dashboard and light chat are fine: the default Docker image uses only 1024 MB of memory and the documentation recommends a machine with at least 2 GB. Running an AI coding tool with long context needs a lot more; the documentation gives 10 GB or more for one tool.

Is using free tiers like this against the terms of service? It depends on the provider. The project keeps a terms-risk catalog and marks some providers itself as "avoid". Read a provider's terms before connecting your account.