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

> Install OmniRoute on Node.js 22+ with our complete setup guide. Clone the repo install dependencies create your env file and run the dev server for a quick start.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-29

---

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

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

```

### Install Dependencies

Install the exact dependency versions locked in [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json) using the clean install command:

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

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

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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts).

## Verify Your Installation

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

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

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

```

### Test the CLI

Verify the CLI installation by listing available provider combos:

```bash
./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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts)
- **Database migrations run automatically** via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) and migrations are automatically applied from the `db/migrations/` directory via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.