# How to Set Up OmniRoute Locally: Complete Installation Guide

> Easily set up OmniRoute locally with this complete installation guide. Follow simple steps to clone, install dependencies, generate secrets, and run the server.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
npm ci

```

The `npm ci` command reads [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json) to produce a deterministic `node_modules` directory. The project's build scripts in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:**

   ```bash
   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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

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

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

```

The health route is implemented in [`src/app/api/monitoring/health/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
npm run build:release

```

This produces a standalone Next.js build in `.next/standalone/` as defined in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json).

## Key Files for Local Development

| Path | Purpose |
|------|---------|
| [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.