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

> Learn how to set up OmniRoute with Next.js App Router. This guide covers installation for zero-configuration deployment, route validation, authentication, and 349 LLM providers.

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

---

**OmniRoute is built on Next.js 16 App Router and exposes OpenAI-compatible endpoints through the `src/app/api/v1/` directory, offering zero-configuration deployment with per-route validation, authentication pipelines, and support for 349 LLM providers.**

The diegosouzapw/OmniRoute repository provides a production-ready AI gateway that leverages Next.js App Router's per-route isolation to handle request validation, policy enforcement, and provider dispatch without global middleware. This architecture enables seamless integration with existing OpenAI-compatible clients while supporting advanced features like combo routing, circuit breakers, and automatic compression.

## Architecture Overview

OmniRoute's App Router implementation eschews global middleware in favor of route-specific handlers. Each endpoint in `src/app/api/v1/` follows a strict pipeline: **CORS handling → Zod validation → optional authentication → handler delegation**.

Unlike traditional Next.js setups that rely on [`middleware.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/middleware.ts), OmniRoute implements guards directly within individual route files. This design pattern, visible in [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts), allows specific routes to apply custom authorization logic via [`src/server/authz/pipeline.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/pipeline.ts) while maintaining complete isolation between endpoints.

The core processing happens in the `open-sse` workspace, where [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) manages request normalization, combo strategy selection, and SSE streaming. The execution layer in `open-sse/executors/` then dispatches to your chosen provider among the supported 349 backends.

## Prerequisites and Installation

You can deploy OmniRoute either globally via CLI or as a local dependency. The installation process bundles the complete Next.js application with all necessary configurations.

**Global CLI installation:**

```bash
npm i -g omniroute

# or

pnpm add omniroute

```

**Local installation:**

```bash
npm install omniroute

```

The package automatically configures the Next.js environment, including the `next.config.mjs` settings required for standalone builds and Turbopack aliases.

## Configuration Deep Dive

OmniRoute's behavior is controlled through `next.config.mjs` at the repository root. This file defines critical deployment parameters including base paths, security headers, and build outputs.

Key configuration properties include:

- **Standalone output**: The `output: "standalone"` setting produces a self-contained binary in `.next/server/` suitable for Docker or Electron deployments
- **Base path configuration**: Sets `basePath` and `assetPrefix` for reverse proxy compatibility
- **Security headers**: Content-security policies and body-size limits
- **Turbopack aliasing**: Stubs MITM modules for minimal builds

```javascript
// next.config.mjs excerpt
export default {
  output: "standalone",
  basePath: process.env.BASE_PATH || "",
  // Security and performance optimizations
  headers: async () => [
    {
      source: "/:path*",
      headers: [
        { key: "X-Content-Type-Options", value: "nosniff" },
      ],
    },
  ],
}

```

## API Route Structure

The App Router implementation resides entirely within `src/app/api/v1/`, with each endpoint defined as a [`route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/route.ts) file exporting HTTP method handlers.

**Core chat completions endpoint:**

The primary integration point is [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts). This route handles POST requests through a validation layer using Zod schemas, then delegates to `handleChatCore()` in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts).

**Available models endpoint:**

[`src/app/api/v1/models/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/models/route.ts) exposes all registered providers, including the zero-configuration `felo/auto` model that works without API keys.

Request flow through the system:
1. Next.js App Router receives request at `/v1/chat/completions`
2. Route handler applies CORS headers
3. Zod validates request body structure
4. Optional authentication via [`src/server/authz/pipeline.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/pipeline.ts)
5. [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) selects provider using 19 available combo strategies
6. `open-sse/executors/` dispatches to chosen LLM backend
7. Response streams back (SSE or JSON) depending on `stream` parameter

## Running OmniRoute

**Development mode:**

Start the dev server on port 20128 using the built-in script:

```bash
npm run dev

# Executes scripts/dev/run-next.mjs

```

This launches the Next.js development server with Turbopack enabled, automatically loading configurations from `next.config.mjs`.

**Testing your installation:**

Verify the setup using the built-in `felo/auto` model (requires no API keys):

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"felo/auto","messages":[{"role":"user","content":"Hello!"}]}'

```

**Listing available models:**

```bash
curl http://localhost:20128/v1/models | jq .

```

**Using the auto-combo feature:**

Route to the best available free provider automatically:

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Explain quantum tunneling"}]}'

```

## Deployment Options

**Standalone production build:**

For production deployments, build a self-contained bundle:

```bash
npm run build    # Uses Turbopack by default

npm run start    # Runs .next/server

```

The standalone output includes all necessary dependencies and respects your `basePath` configuration for reverse proxy deployments.

**Docker deployment:**

The repository includes a `Dockerfile` configured to run the standalone Next.js server. The container respects the same environment variables and routing configurations as the development environment, ensuring consistent behavior between local testing and production.

**Dashboard embedding:**

OmniRoute includes a dashboard UI located at `src/app/(dashboard)/dashboard` that runs on the same server instance. Enable embedding mode via the `dashboardEmbedMode` configuration to integrate the management interface into existing administrative tools.

## Summary

- OmniRoute utilizes Next.js 16 App Router with per-route handlers in `src/app/api/v1/` rather than global middleware
- Installation requires only `npm i -g omniroute` for zero-configuration deployment on port 20128
- The `next.config.mjs` file controls standalone builds, base paths, and security headers essential for production
- Request processing flows through [`src/app/api/v1/chat/completions/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) into [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) for validation and dispatch
- Support for 349 providers and 19 combo strategies operates through the [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) engine
- The `felo/auto` model provides immediate testing capability without API keys
- Standalone output via `output: "standalone"` enables Docker deployment and binary distribution

## Frequently Asked Questions

### How does OmniRoute handle authentication without global middleware?

OmniRoute implements authentication within individual route handlers using [`src/server/authz/pipeline.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/pipeline.ts). Each API route in `src/app/api/v1/` applies its own guards after CORS handling and Zod validation, allowing granular access control per endpoint rather than blanket middleware policies.

### Can I use OmniRoute with existing OpenAI SDK clients?

Yes. OmniRoute exposes fully OpenAI-compatible endpoints at `/v1/chat/completions` and `/v1/models`. Any client configured with `baseURL: "http://localhost:20128/v1"` will function normally, supporting both streaming (SSE) and non-streaming responses through the Next.js App Router handlers.

### What is the difference between the `auto` and `felo/auto` models?

The `felo/auto` model is a specific zero-configuration provider that works immediately without API keys, while `auto` triggers the combo engine in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) to dynamically select from 19 available strategies across all 349 configured providers based on availability, latency, and cost criteria.

### How do I configure OmniRoute behind a corporate reverse proxy?

Set the `basePath` and `assetPrefix` variables in `next.config.mjs` to match your proxy's path mapping. The standalone build respects these settings, ensuring that API routes and dashboard assets resolve correctly when served through nginx, Apache, or cloud load balancers.