How to Set Up OmniRoute with Next.js: Complete Installation Guide

OmniRoute is a unified AI proxy/router built on Next.js 16 App Router that you can set up by cloning the repository, installing dependencies with npm, generating cryptographic secrets, and running the development server on port 20128.

Setting up OmniRoute with Next.js provides you with a self-hosted gateway capable of routing requests to over 350 LLM providers through a unified API. This open-source solution by diegosouzapw/OmniRoute leverages the Next.js 16 App Router architecture to handle streaming responses, load balancing, and failover mechanisms. Follow this guide to install the stable release/v3.8.51 branch and understand the core architectural components.

Step 1: Clone the Repository

Begin by retrieving the source code from GitHub and checking out a specific release branch. Working from a release branch ensures you use a stable version rather than active development code.

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
git checkout release/v3.8.51

Step 2: Install Dependencies

OmniRoute uses npm for package management. The installation process automatically generates a .env file from the .env.example template included in the repository.

npm install

This command installs all Node.js dependencies required for the Next.js 16 App Router and creates your initial environment configuration.

Step 3: Configure Environment Variables

OmniRoute requires two cryptographic secrets for authentication: JWT_SECRET and API_KEY_SECRET. Copy the example environment file and generate secure random values using OpenSSL.

cp .env.example .env

# Generate JWT_SECRET (48 bytes base64)

openssl rand -base64 48 > secret.txt && echo "JWT_SECRET=$(cat secret.txt)" >> .env

# Generate API_KEY_SECRET (32 bytes hex)

openssl rand -hex 32 > secret2.txt && echo "API_KEY_SECRET=$(cat secret2.txt)" >> .env

These secrets secure the API layer defined in src/app/api/v1/, enabling authentication for all proxy requests.

Step 4: Start the Development Server

Launch the Next.js development server to verify your installation. By default, OmniRoute serves both the dashboard and API on port 20128.

npm run dev

Access the dashboard at http://localhost:20128. The application is now ready to proxy requests to any of the 351 supported LLM providers.

Understanding the OmniRoute Architecture

OmniRoute implements a structured architecture within the Next.js framework. Understanding these file locations helps with customization and debugging.

API Route Layer

All LLM provider endpoints live under src/app/api/v1/. Each route follows a standard middleware pattern: CORS headers, Zod schema validation, optional authentication, and handler delegation to the open-sse/handlers/ directory.

Streaming and Routing Engine

The combo routing logic resides in open-sse/services/combo.ts. This module implements routing strategies including priority, weighted, and fusion to determine which provider(s) handle each request. The open-sse/handlers/ directory contains SSE (Server-Sent Events) handlers, executors, and translators that manage streaming responses.

Resilience Mechanisms

OmniRoute includes provider-level circuit breakers and fallback logic to ensure high availability. The circuit breaker implementation is located in src/shared/utils/circuitBreaker.ts, while account fallback strategies are defined in src/sse/services/accountFallback.ts. These modules manage connection cooldowns and model lockouts when providers fail.

Database Layer

The application uses SQLite for data persistence, with domain modules organized under src/lib/db/. The codebase enforces a strict architectural rule: direct SQL is never written in API routes. All database interactions occur through helper functions exported from the database layer.

Verification and Production Build

Validate your installation before deploying to production.

npm run check

This command executes ESLint, unit tests, and Vitest suites to verify code integrity. For production deployments, generate a standalone build:

npm run build

The build process uses next build to create an optimized production bundle. Refer to AGENTS.md in the repository root for project-wide conventions, architecture details, and hard rules governing the codebase.

Summary

• OmniRoute runs on Next.js 16 App Router and requires Node.js with npm.
• Clone the release/v3.8.51 branch and run npm install to auto-generate the .env file.
• Generate JWT_SECRET and API_KEY_SECRET using OpenSSL to secure your API endpoints.
• The development server starts on port 20128 via npm run dev, serving both dashboard and API routes.
• Core routing logic lives in open-sse/services/combo.ts, while resilience mechanisms are implemented in src/shared/utils/circuitBreaker.ts.
• Use npm run check to verify your installation through linting and automated tests.

Frequently Asked Questions

What versions of Next.js does OmniRoute support?

OmniRoute is built specifically for Next.js 16 App Router architecture. The project leverages the App Router's file-based routing system, with all API endpoints defined under src/app/api/v1/ following modern Next.js patterns for handling server-side logic and streaming responses.

How do I generate the required secrets for OmniRoute?

You must create JWT_SECRET and API_KEY_SECRET environment variables using OpenSSL. Run openssl rand -base64 48 to generate the JWT secret and openssl rand -hex 32 for the API key secret, then append these values to your .env file. These cryptographic keys power the authentication layer that protects your proxy endpoints in src/app/api/v1/.

Where is the routing logic implemented in OmniRoute?

The core routing logic resides in open-sse/services/combo.ts, which implements strategies like priority, weighted, and fusion routing. This module decides which LLM provider(s) to call based on your configuration, while resilience mechanisms in src/shared/utils/circuitBreaker.ts handle provider failures through automatic cooldowns and circuit breaking.

How do I verify my OmniRoute installation is working?

Run npm run check to execute linting and test suites, then start the development server with npm run dev. The dashboard should be accessible at http://localhost:20128, indicating that the Next.js application is properly configured and ready to proxy AI requests according to the conventions documented in AGENTS.md.

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