# How to Set Up an OmniRoute Development Environment: Complete Guide

> Quickly set up your OmniRoute development environment. Follow our guide to clone the repo, install Node.js, manage dependencies, set up the database, and start the dev server.

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

---

**To set up an OmniRoute development environment, clone the repository, install Node.js ≥22, run `npm ci` to install dependencies, initialize the SQLite database with `npm run db:setup`, and start the dev server with `npm run dev` on port 20128.**

OmniRoute is a full-stack AI routing gateway built with **Next.js 16**, **TypeScript**, and **SQLite**. Whether you are contributing to the auto-combo routing engine or testing the SSE translation core, this guide walks you through the exact steps to configure your local development stack according to the official source code.

## Prerequisites

Before installing OmniRoute, ensure your system meets the following requirements:

- **Node.js ≥22 <23 or ≥24 <27** (specified in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) engines)
- **Git** for cloning the repository
- **Python 3** (optional) for compiling native SQLite bindings
- **Docker** (optional) for running containerized development modes
- **Electron build tools** (optional) when building the desktop client

These requirements ensure compatibility with the Next.js server and the native dependencies used by the persistence layer.

## Clone and Install Dependencies

Start by cloning the repository and installing the Node packages:

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm ci

```

The `npm ci` command performs a clean install based on the [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json), guaranteeing reproducible builds across environments. After installation, verify code quality:

```bash
npm run lint
npm run typecheck:core

```

## Initialize the SQLite Database

OmniRoute persists provider connections, combos, and usage logs in a local **SQLite** file. By default, this file is created at `~/.omniroute/storage.sqlite`, though you can override this path using the `OMNIROUTE_DATA_DIR` environment variable.

Run the database initialization script:

```bash
npm run db:setup

```

This command executes [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts), which applies **110 schema migrations** located under `db/migrations/` to set up your local database schema.

## Configure Environment Variables

OmniRoute validates its runtime environment through a Zod schema defined in [`src/lib/env/runtimeEnv.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/env/runtimeEnv.ts). Create a `.env.local` file in the repository root to override any defaults:

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | HTTP port for the Next.js server | `20128` |
| `OMNIROUTE_DATA_DIR` | Custom path for SQLite storage | `~/.omniroute/` |
| `REQUIRE_API_KEY` | Toggle API-key enforcement | `false` |
| `OMNIROUTE_BASE_PATH` | Serve under a sub-path | *none* |

## Launch the Development Server

Start the full-stack development environment:

```bash
npm run dev

```

When you run this command, the following services start simultaneously on port `20128`:

- **API routes** (`src/app/api/v1/*`) expose the OpenAI-compatible endpoint at `/v1/*`
- **Dashboard pages** (`src/app/(dashboard)/dashboard/*`) serve the web UI at `http://localhost:20128/dashboard`
- **SSE core** ([`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)) processes streaming requests, handles provider translation, and manages auto-combo routing

## Verify Your Setup

Confirm your environment is running correctly with a quick health check:

```bash
curl -X POST http://localhost:20128/v1/models \
  -H "Content-Type: application/json" \
  -d '{}'

```

You should receive a JSON list of registered models. A **200 OK** response indicates your OmniRoute development environment is ready for use.

## Optional Development Modes

OmniRoute supports several alternative runtime modes for specific use cases:

### Docker Development

Run the full stack in a containerized environment:

```bash
docker compose up

```

Or use the pre-built image: `docker run diegosouzapw/omniroute`. Configuration details are available in [`docs/guides/DOCKER_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md).

### Electron Desktop Client

Build the native desktop application with system tray support:

```bash
npm run electron:dev
npm run electron:build

```

Refer to [`electron/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/README.md) for build-specific requirements.

### Termux (Android)

Run OmniRoute on mobile devices without root access:

```bash
pkg install nodejs
npx -y omniroute

```

See [`docs/guides/TERMUX_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/TERMUX_GUIDE.md) for the complete mobile setup.

### Remote Mode

Control a remote OmniRoute instance via scoped tokens:

```bash
omniroute connect <host>

```

Documentation is available in [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md).

## Run the Test Suite

OmniRoute includes **21,000+ automated tests** covering unit, integration, and end-to-end scenarios:

```bash
npm run test:all        # Full suite (unit + vitest + e2e)

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

npm run test:e2e        # Playwright UI tests

```

Always run `npm run check` (lint + tests) before committing changes to ensure code quality.

## Common Development Tasks

### Add a New Provider Connection

```bash
curl -X POST http://localhost:20128/api/providers \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "name": "my-openai",
    "authType": "apiKey",
    "apiKey": "sk-xxxx"
  }'

```

This endpoint is implemented in [`src/app/api/providers/create/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/providers/create/route.ts).

### Execute a Streaming Chat Request

```bash
curl -N -X POST http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{"role": "user", "content": "Write a quicksort in Python."}],
    "stream": true
  }'

```

The request 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) to the core handler in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts), which manages translation and executor dispatch via [`open-sse/executors/default.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts).

### Enable Guardrails (PII Masking)

```bash
curl -X PUT http://localhost:20128/api/settings/guardrails \
  -H "Content-Type: application/json" \
  -d '{"piiMasking": true}'

```

Guardrail logic resides in `src/lib/guardrails/` and is wired into the request pipeline through [`src/middleware/promptInjectionGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/middleware/promptInjectionGuard.ts).

## Summary

Setting up an OmniRoute development environment requires these key steps:

- Install **Node.js ≥22** and run `npm ci` to install dependencies
- Initialize the **SQLite database** using `npm run db:setup`, which runs [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts)
- Configure environment variables in `.env.local` (validated by [`src/lib/env/runtimeEnv.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/env/runtimeEnv.ts))
- Start the dev server with `npm run dev` to launch the API, dashboard, and SSE core on port **20128**
- Verify the setup with a `curl` request to `http://localhost:20128/v1/models`
- Run the full test suite with `npm run test:all` before submitting changes

## Frequently Asked Questions

### What Node.js version is required for OmniRoute development?

OmniRoute requires **Node.js ≥22 <23 or ≥24 <27**, as specified in the [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) engines field. This ensures compatibility with the Next.js 16 server and TypeScript compilation processes.

### How do I reset the SQLite database during development?

Run `npm run db:reset` to drop and recreate the SQLite file. This command clears all provider connections, combos, and usage logs while re-applying the 110 schema migrations from `db/migrations/`.

### Can I run OmniRoute without installing Node.js locally?

Yes. You can run OmniRoute in **Docker** using `docker compose up` or the pre-built image `diegosouzapw/omniroute`. For mobile development, use **Termux** on Android to install Node.js and run `npx -y omniroute` without a traditional desktop environment.

### How do I enable API key authentication in development?

Set `REQUIRE_API_KEY=true` in your `.env.local` file. This variable is validated by the Zod schema in [`src/lib/env/runtimeEnv.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/env/runtimeEnv.ts) and enforces API-key authentication on public routes when running `npm run dev`.