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

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, OmniRoute implements guards directly within individual route files. This design pattern, visible in src/app/api/v1/chat/completions/route.ts, allows specific routes to apply custom authorization logic via 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 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:

npm i -g omniroute

# or

pnpm add omniroute

Local installation:

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

// 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 file exporting HTTP method handlers.

Core chat completions endpoint:

The primary integration point is 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.

Available models endpoint:

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

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

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

Listing available models:

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

Using the auto-combo feature:

Route to the best available free provider automatically:

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:

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

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