How to Install OmniRoute: A Complete Setup Guide for the Next.js 16 Monorepo

OmniRoute is a Next.js 16 monorepo that requires Node.js 22+, uses SQLite for persistence, and starts with npm run dev after cloning, installing dependencies, and configuring a .env file.

OmniRoute is an open-source LLM request router built as a Next.js 16 application. If you want to learn how to install OmniRoute locally, this guide walks through the exact steps derived from the diegosouzapw/OmniRoute source code, including environment setup, dependency installation, and database initialization.

Prerequisites

Before you install OmniRoute, ensure your environment meets the following requirements:

• Node.js 22 or newer. The engines field in package.json enforces >=22 <23 || >=24 <27.
• A recent version of npm (or pnpm/yarn if you prefer).
• Git for cloning the repository.

Clone the Repository and Install Dependencies

Start by cloning the repo and installing exact dependency versions:

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

The npm ci command installs exact versions from package-lock.json, ensuring a reproducible environment across all three layers of the monorepo: the Next.js web app (src/app/), the core streaming engine (open-sse/), and the SQLite data layer (src/lib/db/).

Configure Environment Variables

Create a .env file in the project root. The essential variables are:

• DATA_DIR — directory where the SQLite database is stored (defaults to ~/.omniroute/).
• REQUIRE_API_KEY — set to true to enforce API-key authentication for the public API.
• Provider-specific keys (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY) — add only the keys you plan to use.

The application never logs secret values. Instead, they are validated by src/shared/validation/providerSchema.ts, which prevents accidental misspelling of provider IDs or configuration errors.

Initialize the SQLite Database

OmniRoute uses a SQLite database for persistent configuration, provider catalogs, combos, and usage tracking.

The first start automatically applies all pending migrations located in db/migrations/. You do not need to run anything manually. The migration runner at src/lib/db/migrationRunner.ts creates the base tables defined in src/lib/db/core.ts and applies the 110 versioned schema files on startup.

Start the Development Server

Launch the Next.js development server with:

npm run dev

This starts the application on http://localhost:3000 and makes all API routes under src/app/api/v1/ available. For example, you can immediately send requests to POST /api/v1/chat/completions, which is handled by src/app/api/v1/chat/completions/route.ts.

Production Build

For a production deployment, use the build pipeline:

npm run build
npm run start

The npm run build command creates a Next.js build in .build/next, and npm run start runs the compiled server.

Optional: Build the CLI Package

OmniRoute ships with a CLI binary (omniroute) for local testing and MCP usage. Compile it with:

npm run build:cli

This produces a binary in dist/ that you can invoke directly.

Verify the Installation

Run the full test suite to confirm routing, providers, compression, and MCP tools are working:

npm run test:all

All tests should pass. Failures usually indicate a missing environment variable or an outdated Node version.

You can also verify the running server with a cURL request to the unified chat endpoint:

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
      }'

Verify the CLI

After building the CLI, list available provider combos:

./dist/omniroute combo list

Verify MCP Tools over SSE

OmniRoute exposes 94 MCP tools via the SSE transport. You can test tool invocation with:

curl -N -H "Accept: text/event-stream" \
     http://localhost:3000/api/mcp/sse \
     -d '{"jsonrpc":"2.0","method":"list_combos","id":"1"}'

Test a Custom Compression Combo

OmniRoute supports prompt compression via combos stored in src/lib/db/compressionCombos.ts. After adding a combo definition:

// src/lib/db/compressionCombos.ts (example snippet)
/*
{
  id: "lite-01",
  name: "Lite Combo",
  mode: "lite",
  thresholds: { tokenCount: 2000 }
}
*/

Restart the server and reference it in an API call:

curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","compressionComboId":"lite-01","messages":[...]}'

Summary

• OmniRoute requires Node.js 22+ and uses npm ci for deterministic installs.
• Configuration lives in a root .env file, validated by src/shared/validation/providerSchema.ts.
• The SQLite database auto-migrates on first startup via src/lib/db/migrationRunner.ts.
• Start locally with npm run dev, or build for production with npm run build followed by npm run start.
• Optionally build the CLI with npm run build:cli for local MCP and combo testing.

Frequently Asked Questions

What versions of Node.js are supported by OmniRoute?

OmniRoute targets Node.js 22 or newer. According to the engines field in package.json, supported ranges are >=22 <23 || >=24 <27. Running an older version will prevent installation or cause runtime errors.

Is manual database migration required?

No. The src/lib/db/migrationRunner.ts module applies all pending SQL migrations from db/migrations/ automatically when the server starts. It creates the base schema defined in src/lib/db/core.ts and handles all 110 versioned schema files without manual intervention.

How are provider API keys validated?

Provider keys and configurations are validated by the Zod schema in src/shared/validation/providerSchema.ts. This ensures that provider IDs are not misspelled and that configuration objects match the expected shape before any request reaches the streaming engine in open-sse/handlers/chat.ts.

Can I use OmniRoute without the Next.js web frontend?

The primary interface is the Next.js 16 application in src/app/, but you can also build the standalone CLI with npm run build:cli. The CLI binary in dist/ supports combo management and MCP interactions independently of the browser-based UI.

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