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

> Install OmniRoute for Next.js 16 monorepos with ease. Follow our complete setup guide for Node.js 22+, SQLite, and quick project initiation. Get started now.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: getting-started
- Published: 2026-07-24

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

```

The `npm ci` command installs exact versions from [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) creates the base tables defined in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts).

### Production Build

For a production deployment, use the build pipeline:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
./dist/omniroute combo list

```

### Verify MCP Tools over SSE

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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compressionCombos.ts). After adding a combo definition:

```typescript
// 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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts).
- The **SQLite database** auto-migrates on first startup via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.