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

> Learn how to set up OmniRoute with Next.js by cloning the repo, installing dependencies, generating secrets, and running the server. Your complete AI proxy installation guide.

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

---

**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.

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

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

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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts), while account fallback strategies are defined in [`src/sse/services/accountFallback.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```bash
npm run check

```

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

```bash
npm run build

```

The build process uses `next build` to create an optimized production bundle. Refer to [`AGENTS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), while resilience mechanisms are implemented in [`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/AGENTS.md).