How to Set Up OmniRoute Locally: Complete Installation Guide

To set up OmniRoute locally, clone the repository, install dependencies with npm ci, generate secrets from .env.example, and run npm run dev to start the server on port 20128.

OmniRoute is a Next.js 16 monorepo that provides a unified AI proxy and router supporting 353 LLM providers with auto-fallback capabilities. Setting it up locally follows a streamlined process documented in the official AGENTS.md file according to the diegosouzapw/OmniRoute source code.

Clone the OmniRoute Repository

Start by cloning the repository and checking out the release branch you want to work with.

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

The repository structure is detailed in the Repository map section of AGENTS.md, which describes how the monorepo organizes its Next.js app, SSE streaming engine, and supporting libraries.

Install Dependencies

Use npm's clean install command to ensure reproducible builds:

npm ci

The npm ci command reads package-lock.json to produce a deterministic node_modules directory. The project's build scripts in package.json depend on this exact package set for consistent behavior across environments.

Configure Environment Variables

OmniRoute requires specific secrets for authentication and encryption. Follow these steps:

1. Copy the example environment file:

   cp .env.example .env

2. Generate required secrets — the example file contains placeholders that must be replaced:

   • JWT_SECRET: Generate with openssl rand -base64 48
   • API_KEY_SECRET: Generate with openssl rand -hex 32

These secrets power the authentication middleware in src/server/authz/* and the JWT utilities in src/lib/auth/jwt.ts as implemented in diegosouzapw/OmniRoute.

3. (Optional) Customize additional variables such as PORT, APP_LOG_LEVEL, or feature flags. The defaults work for local development.

Start the Development Server

Launch the local server with:

npm run dev

This command boots both the Next.js application (src/app/) and the SSE streaming engine (open-sse/). By default, the dashboard is available at http://localhost:20128, with API routes under /api/v1/.

Verify Your Local Setup

Confirm everything works by running the test suite:

npm run test:coverage   # Unit tests with coverage gate

npm run test:vitest     # MCP and auto-combo tests

npm run lint            # ESLint validation

Successful execution proves your local OmniRoute setup matches the repository's expected state.

Working with the Local OmniRoute Instance

Health Check Endpoint

Verify the server status:

curl http://localhost:20128/api/monitoring/health/route

The health route is implemented in src/app/api/monitoring/health/route.ts and reports provider circuit breaker status and connection cooldowns.

Send a Chat Completion Request

Test the routing functionality:

curl -X POST http://localhost:20128/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4o",
        "messages": [{"role":"user","content":"Hello, OmniRoute!"}]
      }'

Requests are processed by open-sse/handlers/chatCore.ts, which routes through the combo router, applies resilience logic, and streams responses via SSE.

Build for Production

When ready to deploy:

npm run build:release

This produces a standalone Next.js build in .next/standalone/ as defined in package.json.

Key Files for Local Development

Path	Purpose
package.json	Dependency list and npm scripts
.env.example	Template for required environment variables
src/app/api/v1/	API entry points (Next.js App Router)
open-sse/handlers/	Core request processing (chat, embeddings)
open-sse/services/	Combo routing and resilience mechanisms
src/lib/db/	SQLite domain modules and migrations
src/lib/skills/	Extensible skill framework for MCP tools
open-sse/mcp-server/	MCP server for tool orchestration
AGENTS.md	Central documentation and architecture reference

Summary

• Clone and checkout the release branch from diegosouzapw/OmniRoute
• Use npm ci for reproducible dependency installation
• Generate secrets (JWT_SECRET, API_KEY_SECRET) before starting
• Run npm run dev to launch on port 20128 with dashboard and API
• Execute test suite to validate your local OmniRoute setup
• Reference AGENTS.md for authoritative configuration details

Frequently Asked Questions

What Node.js version does OmniRoute require?

OmniRoute is built on Next.js 16, which requires Node.js 18.17 or later. Check your version with node --version before running npm ci.

Can I change the default port from 20128?

Yes. Set the PORT environment variable in your .env file. The server reads this value during startup in the Next.js app configuration.

Where are API requests routed after reaching the server?

Incoming requests hit src/app/api/v1/ routes, then pass to handlers in open-sse/handlers/ like chatCore.ts. The combo router in open-sse/services/ applies provider selection, fallback logic, and circuit breaker patterns before returning streamed responses.

How do I add a new LLM provider to my local instance?

Provider configurations are managed through the dashboard or database layer in src/lib/db/. The system supports 353 providers out of the box; adding custom providers requires updating the provider registry and ensuring your API_KEY_SECRET can validate the new endpoint credentials.

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