# How to Set Up and Install OmniRoute: Complete Installation Guide

> Install OmniRoute easily with our complete guide. Clone the repo, set up Node.js, install dependencies, configure your environment, and launch the dev server. Get started today!

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

---

**TLDR:** To set up and install OmniRoute, clone the repository, ensure you are running Node.js 22 or newer, run `npm ci` to install exact dependencies, create a `.env` file with your `DATA_DIR` and provider API keys, and launch the development server with `npm run dev` on `http://localhost:3000`.

OmniRoute is a Next.js 16 application that serves as a unified AI gateway for routing LLM requests through multiple providers. According to the diegosouzapw/OmniRoute source code, the repository is structured as a monorepo with three distinct layers: a Next.js web app for HTTP APIs and UI, an `open-sse` workspace containing the core streaming engine, and a SQLite data layer for persistent configuration. This guide provides the complete sequence to get the application running locally or in production.

## Prerequisites and System Requirements

Before installing OmniRoute, verify your environment meets the strict version requirements. The `engines` field in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) enforces Node.js `>=22 <23 || >=24 <27`, meaning you must use Node 22 or Node 24+. You also need a recent version of **npm**, **pnpm**, or **yarn** to install dependencies. Git is optional but recommended for cloning the repository.

## Step-by-Step Installation Guide

### 1. Clone the Repository

Clone the official repository and navigate into the project directory:

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

```

### 2. Install Dependencies

Install the exact dependency versions locked in [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json) to ensure reproducible builds:

```bash
npm ci

```

### 3. Configure Environment Variables

Create a `.env` file in the project root and define the essential configuration variables:

- **`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** – Add only the keys you plan to use (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).

The application validates these secrets using the Zod schema defined in [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts), ensuring provider IDs and configurations are correct before the server starts. OmniRoute never logs secret values to the console.

### 4. Initialize the Database

OmniRoute automatically applies database migrations on first startup. The migration runner located at [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) executes all pending SQL files from `db/migrations/` and initializes the base schema defined in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts). This process creates the necessary tables for provider catalogs, combos, and usage tracking without requiring manual intervention.

### 5. Start the Development Server

Launch the Next.js development server:

```bash
npm run dev

```

This exposes all API routes under `src/app/api/v1/`, including the main Chat Completions endpoint 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). The server listens on `http://localhost:3000`.

### 6. Build for Production

For production deployments, create an optimized build and start the compiled server:

```bash
npm run build   # Outputs to .build/next

npm run start

```

## Optional: Install the CLI

OmniRoute ships with a command-line interface (`omniroute`) for local testing and MCP usage. Build the binary with:

```bash
npm run build:cli

```

This produces an executable in the `dist/` directory. You can then invoke it directly to list available provider combos:

```bash
./dist/omniroute combo list

```

## 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 incompatible Node.js version.

To manually verify the API is responding, send a request to the unified completions 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
      }'

```

## Key Architecture Components

Understanding the three-layer architecture helps troubleshoot installation issues:

- **Next.js Web App (`src/app/`)**: Handles HTTP API routes and server-side logic. The main entry point [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) validates incoming requests against Zod schemas before delegating to the streaming handler in [`open-sse/handlers/chat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chat.ts).
- **Open-SSE Workspace (`open-sse/`)**: Contains the core streaming engine. The [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) file handles communication with OpenAI-compatible providers, while [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) implements the auto-combo routing engine.
- **SQLite Data Layer (`src/lib/db/`)**: Manages persistent configuration, provider catalogs, and compression combos. The database connection is initialized in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) and exposed via [`src/lib/localDb.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/localDb.ts).

## Summary

- **Node.js 22+ is mandatory** – The application enforces `>=22 <23 || >=24 <27` in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json).
- **Use `npm ci`** for deterministic dependency installation from the lockfile.
- **Environment configuration** requires `DATA_DIR`, `REQUIRE_API_KEY`, and provider-specific API keys validated 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 startup.
- **Development server** starts with `npm run dev` on port 3000, while production requires `npm run build` followed by `npm run start`.
- **Optional CLI** can be built with `npm run build:cli` for local testing and MCP interactions.

## Frequently Asked Questions

### What Node.js version is required for OmniRoute?

OmniRoute requires Node.js 22 or newer, specifically 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 install or run on Node 20 or earlier versions.

### How do I configure API keys for different providers?

Provider API keys are set as environment variables in your `.env` file (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). The application validates these keys using the Zod schema in [`src/shared/validation/providerSchema.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts) during startup to prevent configuration errors. Only add keys for the providers you intend to use.

### Where is the SQLite database stored?

By default, the SQLite database is stored in `~/.omniroute/`, but you can customize this location by setting the `DATA_DIR` environment variable. The database schema is initialized automatically by the migration runner in [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) on first startup.

### How do I run OmniRoute in production mode?

For production, run `npm run build` to create a Next.js optimized build in `.build/next`, then start the server with `npm run start`. Ensure all environment variables are properly configured before building, as the application reads configuration during both the build and runtime phases.