# How to Set Up a Development Environment for OmniRoute: A Complete Guide

> Effortlessly set up your OmniRoute development environment. Follow this guide to install Node.js, clone the repo, install dependencies, set up the database, and launch the dev server.

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

---

**Setting up an OmniRoute development environment requires Node.js ≥22, cloning the repository, installing dependencies with `npm ci`, initializing the SQLite database with `npm run db:setup`, and launching the dev server with `npm run dev` on port 20128.**

OmniRoute is a full-stack AI routing gateway built with **Next.js 16**, **TypeScript 6**, and a **SQLite** persistence layer. Its architecture combines an API & routing layer, an SSE + translation core, and a persistence layer wired together by services for auto-combo routing, guardrails, and MCP/A2A agents. This guide walks through setting up a local development environment using the actual source files and commands implemented in the `diegosouzapw/OmniRoute` repository.

## Prerequisites and System Requirements

OmniRoute enforces strict engine requirements defined in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) to ensure compatibility with its Next.js server and TypeScript compiler.

### Required Software

- **Node.js ≥22 <23 or ≥24 <27** — The runtime specified in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) engines field.
- **Git** — For cloning the repository and keeping sub-modules in sync.
- **Python 3** — Optional but recommended for compiling native SQLite bindings.

### Optional Tools for Extended Development

- **Docker** — Enables containerized deployment mode using the included `Dockerfile`.
- **Electron build tools** — Required only when building the desktop client (`npm run electron:build`).

## Clone and Install Dependencies

Clone the repository and navigate to the project root, which contains the Next.js application (`src/`), the SSE workspace (`open-sse/`), and the database layer (`src/lib/db/`).

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

```

Install dependencies using a clean install to honor the exact dependency graph in [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json).

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

```

The `npm run lint` command verifies code style with Prettier and ESLint, while `npm run typecheck:core` performs fast type-checking of core files.

## Initialize the SQLite Database

OmniRoute stores 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 with the `OMNIROUTE_DATA_DIR` environment variable.

```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/`. If you need to reset the database during development, run `npm run db:reset` to drop and recreate the file.

## Configure Environment Variables

Environment validation is handled by 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 at the repository root to override any defaults.

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | HTTP port for the Next.js server and dashboard. | `20128` |
| `OMNIROUTE_DATA_DIR` | Custom path for SQLite storage. | `~/.omniroute/` |
| `REQUIRE_API_KEY` | Toggle API-key enforcement for public routes. | `false` |
| `OMNIROUTE_BASE_PATH` | Serve OmniRoute under a sub-path (e.g., `/omniroute/`). | *none* |

## Launch the Development Server

Start the development server with a single command.

```bash
npm run dev

```

This launches three integrated components:

- **API routes** (`src/app/api/v1/*`) — Exposes the OpenAI-compatible endpoint at `/v1/*`.
- **Dashboard pages** (`src/app/(dashboard)/dashboard/*`) — Renders 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, performs provider translation via `open-sse/translator/*`, and applies auto-combo routing via `open-sse/services/autoCombo/*`.

Verify the setup by listing registered models:

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

```

A **200 OK** response with a JSON model list confirms your development environment is ready.

## Run the Test Suite

OmniRoute ships with **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

```

Run `npm run check` before committing to execute both linting and the full test suite.

## Optional Development Modes

Beyond the standard Next.js dev server, OmniRoute supports several alternative deployment targets.

### Docker Deployment

Run the multi-arch container that encapsulates the same server environment:

```bash
docker compose up

# Or

docker run diegosouzapw/omniroute

```

Refer to [`docs/guides/DOCKER_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md) for detailed container configuration.

### Electron Desktop Client

Build a native desktop application with system tray integration:

```bash
npm run electron:dev    # Development mode

npm run electron:build  # Production build

```

Configuration details are available in [`electron/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/README.md).

### Termux Mobile Development

Run OmniRoute on Android 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 mobile-specific instructions.

### Remote Mode

Control a remote OmniRoute instance via scoped tokens:

```bash
omniroute connect <host>

```

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

## Summary

- **Node.js ≥22** is strictly required; verify version compatibility before installing dependencies.
- Run `npm run db:setup` to execute **110 migrations** via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) and initialize the SQLite database at `~/.omniroute/storage.sqlite`.
- The development server starts on **port 20128** and simultaneously serves the API, dashboard, and SSE core.
- Execute **21,000+ tests** using `npm run test:all` to validate changes before committing.
- Alternative modes (Docker, Electron, Termux, Remote) are available for specialized deployment scenarios.

## Frequently Asked Questions

### What Node.js version does OmniRoute require?

OmniRoute requires **Node.js ≥22 <23 or ≥24 <27**, as specified in the `engines` field of [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json). Using versions outside these ranges may cause compatibility issues with the Next.js 16 runtime or TypeScript 6 compiler.

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

Run `npm run db:reset` to drop and recreate the SQLite file. This command removes all existing data and re-applies the **110 schema migrations** stored in `db/migrations/`, giving you a clean state for testing.

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

Yes. You can use the **Docker** mode by running `docker run diegosouzapw/omniroute`, or deploy to **Termux** on Android using `npx -y omniroute`. Both methods bypass the need for a local Node.js installation while providing full gateway functionality.

### Where are the database migrations stored?

All **110 schema migrations** reside in the `db/migrations/` directory and are applied by [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts). This script runs automatically during `npm run db:setup`, creating the necessary tables for providers, combos, and usage logs in the SQLite file defined by `OMNIROUTE_DATA_DIR`.