How to Set Up and Install OmniRoute: Complete Installation Guide

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

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

2. Install Dependencies

Install the exact dependency versions locked in package-lock.json to ensure reproducible builds:

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, 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 executes all pending SQL files from db/migrations/ and initializes the base schema defined in 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:

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. The server listens on http://localhost:3000.

6. Build for Production

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

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:

npm run build:cli

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

./dist/omniroute combo list

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

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

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 validates incoming requests against Zod schemas before delegating to the streaming handler in open-sse/handlers/chat.ts.
• Open-SSE Workspace (open-sse/): Contains the core streaming engine. The open-sse/executors/default.ts file handles communication with OpenAI-compatible providers, while 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 and exposed via src/lib/localDb.ts.

Summary

• Node.js 22+ is mandatory – The application enforces >=22 <23 || >=24 <27 in 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.
• Database migrations run automatically via 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. 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 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 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.

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