How to Install OmniRoute: A Complete Setup Guide for Node.js 22+

To install OmniRoute, clone the repository from GitHub, run npm ci to install dependencies, create a .env file with your provider API keys, and start the development server with npm run dev on Node.js 22 or newer.

OmniRoute is an open-source Next.js 16 application that provides a unified API routing layer for LLM providers. Installing it requires Node.js 22+ and sets up a monorepo with three distinct layers: a Next.js web app, an open-sse workspace for streaming, and a SQLite data layer. This guide walks you through the complete installation process using the exact file paths and configuration options defined in the source code.

Prerequisites

Before installing OmniRoute, ensure your system meets the Node.js version requirements specified in the engines field of package.json. The application requires Node.js version 22 or newer, with support for Node.js 24 through 26 (>=22 <23 || >=24 <27). You will also need a recent version of npm, pnpm, or yarn for dependency management.

Installation Steps

Clone the Repository

Start by cloning the OmniRoute repository and navigating into the project directory:

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute

Install Dependencies

Install the exact dependency versions locked in package-lock.json using the clean install command:

npm ci

This command ensures reproducible builds by respecting the lockfile, which is critical for the monorepo structure containing the Next.js app and open-sse workspace.

Configure Environment Variables

Create a .env file in the project root to configure the application. The essential variables include:

• DATA_DIR: Directory path where the SQLite database is stored (defaults to ~/.omniroute/)
• REQUIRE_API_KEY: Set to true to enforce API-key authentication for public API routes
• Provider-specific keys: Add only the keys you plan to use, such as OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

According to the OmniRoute source code, the application never logs secret values. Instead, they are validated by src/shared/validation/providerSchema.ts, which uses Zod schemas to prevent accidental misspelling and ensure every provider ID is properly configured.

Initialize the Database

OmniRoute automatically applies database migrations on first start. The migration runner located at src/lib/db/migrationRunner.ts creates the base tables defined in src/lib/db/core.ts and applies all versioned schema files from db/migrations/. No manual migration step is required; the singleton better-sqlite3 instance initializes automatically when the server starts.

Start the Development Server

Launch the Next.js development server to make the API routes available:

npm run dev

This starts the server on http://localhost:3000 and exposes all API endpoints under src/app/api/v1/, including the main entry point at src/app/api/v1/chat/completions/route.ts that validates Zod schemas and delegates to the SSE handler.

Optional: Build the CLI

OmniRoute ships with a CLI binary for local testing and MCP usage. To build it:

npm run build:cli

This produces an executable in the dist/ directory, accessible via ./dist/omniroute.

Production Deployment

For production environments, build the application and start the compiled server:

npm run build   # Creates a Next.js build in .build/next

npm run start   # Runs the compiled server

The build process compiles the streaming handlers from open-sse/handlers/, executors from open-sse/executors/, and the combo routing engine from open-sse/services/combo.ts.

Verify Your Installation

Run the comprehensive test suite to validate routing, providers, compression, and MCP tools:

npm run test:all

All tests should pass. Failures typically indicate missing environment variables or an outdated Node version.

Test the Unified API Endpoint

Send a test request to the chat completions endpoint to verify the installation:

curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4o-mini",
        "messages": [{ "role": "user", "content": "Hello, OmniRoute!" }],
        "stream": false
      }'

Test the CLI

Verify the CLI installation by listing available provider combos:

./dist/omniroute combo list

Understanding the Architecture

After installation, the repository structure consists of three main layers as implemented in the source code:

• Next.js Web App (src/app/): Handles HTTP API routes, UI, and server-side logic, with the main entry point at src/app/api/v1/chat/completions/route.ts
• Open-SSE Workspace (open-sse/): Contains the core streaming engine, request routing, providers, translators in open-sse/handlers/, and executors in open-sse/executors/
• SQLite Data Layer (src/lib/db/): Manages persistent configuration, provider catalogs, and compression combos, re-exported via src/lib/localDb.ts

Summary

• OmniRoute requires Node.js 22+ and uses npm ci for dependency installation
• Configuration happens via .env with validation handled by src/shared/validation/providerSchema.ts
• Database migrations run automatically via src/lib/db/migrationRunner.ts on first start
• Development server starts with npm run dev on port 3000
• Production builds use npm run build and npm run start
• CLI tools can be built separately using npm run build:cli
• Verify installation with npm run test:all and sample API calls to /api/v1/chat/completions

Frequently Asked Questions

What Node.js version do I need for OmniRoute?

OmniRoute requires Node.js version 22 or newer, specifically supporting versions >=22 <23 || >=24 <27 as defined in the engines field of package.json. The application will not start on older versions, and the test suite may fail if your Node version is outdated.

Where does OmniRoute store its configuration data?

By default, OmniRoute stores its SQLite database in ~/.omniroute/, though you can customize this location using the DATA_DIR environment variable. The database schema is managed by src/lib/db/core.ts and migrations are automatically applied from the db/migrations/ directory via src/lib/db/migrationRunner.ts.

How do I add my OpenAI or Anthropic API keys?

Create a .env file in the project root and add provider-specific keys such as OPENAI_API_KEY or ANTHROPIC_API_KEY. Only add keys for providers you plan to use. The validation schema in src/shared/validation/providerSchema.ts ensures these secrets are properly formatted and prevents typos in provider IDs.

Can I install OmniRoute without using the development server?

Yes, for production deployments you can build the application with npm run build and start it with npm run start. Additionally, you can build the standalone CLI using npm run build:cli to use OmniRoute features without running the full Next.js web server, though the SQLite data layer and API routes require the server to be running for full functionality.

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