How to Install OmniRoute Locally: Complete Setup Guide

OmniRoute installs locally via npm, Docker, or source using Node ≥ 22, creating an encrypted credential store at ~/.omniroute/ and exposing a unified /v1 endpoint on port 20128.

OmniRoute is a self‑hosted AI gateway that aggregates roughly 250 providers (90+ free tiers) behind a single OpenAI‑compatible API. According to the diegosouzapw/OmniRoute repository, installing locally requires only Node.js or Docker, a writable home directory, and three configuration steps to start routing requests through your own infrastructure.

Prerequisites

Before installing OmniRoute locally, ensure your environment meets the baseline requirements.

• Node.js ≥ 22 or Docker (supports AMD64 and ARM64 architectures)
• A writable home directory for the encrypted credential store (~/.omniroute/)
• Approximately 500 MB of disk space for dependencies and the SQLite database

The credential store uses AES‑256‑GCM encryption at rest, meaning all provider API keys are secured locally before the gateway starts accepting traffic.

Installation Methods

Choose the delivery method that matches your platform and use case. The package.json in the repository declares the CLI entry point (bin.omniroute) and scripts for both development and production builds.

Install via npm (Global)

The fastest method for Node.js users installs the omniroute binary directly to your $PATH.

# Install globally

npm install -g omniroute

# Verify installation

omniroute --version

# Start the gateway (default port 20128)

omniroute

This command places the executable in your global npm directory and immediately makes the dashboard available at http://localhost:20128.

Run with Docker

For containerized environments or users who prefer not to manage Node.js versions, pull the official multi‑arch image.

docker run -d \
  -p 20128:20128 \
  -v "$HOME/.omniroute:/root/.omniroute" \
  --name omniroute \
  diegosouzapw/omniRoute:latest

The volume mapping persists your encrypted credential store and SQLite database (~/.omniroute/) across container restarts. See docs/guides/DOCKER_GUIDE.md in the repository for environment variables and advanced networking options.

Build from Source

Contributors or users requiring custom builds should clone the repository and use the lockfile for reproducible dependencies.

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm ci                # install exact lockfile deps

npm run dev           # launches Next.js dev server on http://localhost:3000

For production builds, execute npm run build && npm run start instead of npm run dev. The build process compiles the Next.js routes (including src/app/api/v1/chat/completions/route.ts) and the core pipeline handlers (open-sse/handlers/chatCore.ts) into the server bundle.

Desktop Application (Electron)

Cross‑platform users can run OmniRoute as a desktop application. The electron/README.md file contains build instructions for packaging the gateway into a native executable that manages the Node.js runtime internally.

First‑Run Configuration

After installation, initialize the local database and import provider credentials.

# Interactive setup wizard

omniroute setup

Alternatively, start the server and open the browser interface manually:

npm run start

# Then open http://localhost:20128

The setup wizard generates a local SQLite database (managed through src/lib/db/localDb.ts) and configures the encryption keys for the credential store. Add provider keys using the CLI or the web dashboard at /settings/providers:

omniroute provider add openai --api-key sk-....

The request routing logic in open-sse/executors/default.ts uses these stored credentials to authenticate against the 250+ supported providers while the compression engine configuration (defined in src/lib/db/compressionCombos.ts) optimizes payload sizes.

Security and Privacy

All components run locally with no telemetry sent unless explicitly enabled. Credentials remain encrypted at rest in ~/.omniroute/ using AES‑256‑GCM.

To disable any outbound usage reporting, start the gateway in private mode:

OMNIROUTE_PRIVATE=true omniroute

This environment variable ensures the installation operates entirely offline, routing requests only to the providers you configure without external health checks or analytics.

Verifying the Installation

Confirm the gateway is operational by checking the health endpoint:

curl http://localhost:20128/healthz | jq .

Test the unified /v1 endpoint with any OpenAI‑compatible CLI:

export OMIROUTE_ENDPOINT=http://localhost:20128/v1

# Example with the official OpenAI CLI

openai api chat.completions.create -m gpt-4 -p "Hello"

The src/app/api/v1/chat/completions/route.ts file receives these requests and forwards them through the core pipeline (open-sse/handlers/chatCore.ts), returning responses in standard OpenAI format.

Summary

• OmniRoute installs locally via npm (npm install -g omniroute), Docker (diegosouzapw/omniroute), or source build with Node ≥ 22.
• The setup creates an encrypted credential store at ~/.omniroute/ using AES‑256‑GCM and initializes a SQLite database for provider configuration.
• Run omniroute setup or start with npm run start to launch the dashboard on port 20128.
• Enable private mode with OMNIROUTE_PRIVATE=true to ensure zero telemetry.
• Key source files include the Next.js route handler (src/app/api/v1/chat/completions/route.ts), core request pipeline (open-sse/handlers/chatCore.ts), and database layer (src/lib/db/localDb.ts).

Frequently Asked Questions

What is the minimum Node.js version required for OmniRoute?

OmniRoute requires Node.js version 22 or higher. This version provides the necessary crypto APIs for AES‑256‑GCM encryption used in the credential store and supports the native fetch implementation required by the core executor (open-sse/executors/default.ts).

Can I run OmniRoute without installing Node.js?

Yes. Use the official Docker image diegosouzapw/omniroute which bundles Node.js and all dependencies. The image supports both AMD64 and ARM64 architectures, making it suitable for cloud servers, local desktops, and even ARM‑based devices like Raspberry Pi or Apple Silicon.

Where are my API keys stored when running locally?

Provider API keys are stored in an encrypted SQLite database inside ~/.omniroute/. The encryption uses AES‑256‑GCM, and the database is managed by the local persistence layer (src/lib/db/localDb.ts). When using Docker, mount this directory as a volume to ensure keys persist across container restarts.

How do I add new providers after the initial installation?

Use the interactive command omniroute provider add <provider-name> --api-key <key> or navigate to http://localhost:20128/settings/providers in the web dashboard. The provider configuration is saved to the local database and immediately becomes available to the routing logic in open-sse/handlers/chatCore.ts without restarting the server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}