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

> Set up your OmniRoute development environment easily. Follow this guide to clone the repo, install dependencies, set up the database, and launch the dev server locally.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: getting-started
- Published: 2026-07-24

---

**Setting up an OmniRoute development environment requires Node.js ≥22, cloning the repository, running `npm install` and `npm run db:setup` to initialize the SQLite database, then 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**, and a SQLite persistence layer. This guide walks you through configuring a complete OmniRoute development environment on your local machine, referencing the exact source files and commands used in the diegosouzapw/OmniRoute repository.

## Prerequisites

Before installing, ensure your system meets these requirements:

- **Node.js ≥22 (and <23) or ≥24 (and <27)** — Required by the Next.js server and TypeScript compiler as specified in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) engines.
- **Git** — To clone the repository and manage submodules.
- **Python 3** — Optional, needed only if native bindings (e.g., SQLite) must be compiled from source.
- **Docker** — Optional, enables testing the Docker run mode and containerized deployments.

## Clone the Repository

Start by cloning the official repository and entering the project directory:

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

```

The repository root contains the **Next.js application** (`src/`), the **SSE workspace** (`open-sse/`), and the **database layer** (`src/lib/db/`).

## Install Dependencies

Install the exact dependency graph using the lockfile, then verify code quality:

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

```

The `npm ci` command guarantees reproducible builds by honoring [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json). The `lint` script runs Prettier and ESLint, while `typecheck:core` performs fast type‑checking of core files.

## Initialize the SQLite Database

OmniRoute persists all provider connections, combos, and usage logs in a local **SQLite** file. By default, this file lives at `~/.omniroute/storage.sqlite`, though you can override the 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 create the database schema.

To reset the database during development, use:

```bash
npm run db:reset

```

This drops and recreates the SQLite file, clearing all data.

## 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 at the repository root to override these defaults:

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

## Launch the Development Server

Start the full development stack with:

```bash
npm run dev

```

This command launches three integrated components simultaneously:

- **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 logic.

Once running, you can route any OpenAI‑compatible client to **`http://localhost:20128/v1`**.

## Run the Test Suite

OmniRoute ships with **21,000+ automated tests** covering unit, integration, and end‑to‑end scenarios. Execute the full suite before committing changes:

```bash
npm run test:all

```

For specific test categories:

- `npm run test:vitest` — Runs MCP server and auto‑combo tests.
- `npm run test:e2e` — Executes Playwright UI tests.

Use `npm run check` to run both linting and tests in a single command.

## Optional Development Modes

OmniRoute supports multiple deployment targets beyond the standard Next.js dev server:

**Docker Mode** — Run `docker compose up` or `docker run diegosouzapw/omniroute` to launch a multi‑arch container. See [`docs/guides/DOCKER_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/DOCKER_GUIDE.md) for details.

**Electron Desktop** — Build a native desktop window with system tray support using `npm run electron:dev` or `npm run electron:build`. Refer to [`electron/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/README.md) for build requirements.

**Termux (Android)** — Install Node.js via `pkg install nodejs` then run `npx -y omniroute` to operate on mobile devices without root access. Documentation lives in [`docs/guides/TERMUX_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/TERMUX_GUIDE.md).

**Remote Mode** — Control a remote OmniRoute instance using scoped tokens with `omniroute connect <host>`. See [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md) for authentication setup.

**Progressive Web App** — Open the dashboard in a browser and select **"Add to Home Screen"** to install the UI as a PWA.

## Verify Your Setup

Confirm your OmniRoute development environment is operational with a health check:

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

```

A successful response returns a JSON list of registered models including auto‑combo aliases. If you receive **200 OK**, your environment is ready for development.

## Summary

- **OmniRoute development environment** setup requires Node.js ≥22, Git, and optionally Python 3 or Docker.
- Install dependencies with `npm ci`, then 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 custom paths and security settings via environment variables validated in [`src/lib/env/runtimeEnv.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/env/runtimeEnv.ts).
- Launch the stack with `npm run dev` to start the API, dashboard, and SSE core on port 20128.
- Validate functionality by querying `http://localhost:20128/v1/models` or running the 21,000+ test suite with `npm run test:all`.

## Frequently Asked Questions

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

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

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

Run `npm run db:reset` to drop and recreate the SQLite file at `~/.omniroute/storage.sqlite`. This command triggers [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts) to reapply all 110 migrations to a fresh database instance.

### Can I change the default data directory for SQLite?

Yes. Set the **`OMNIROUTE_DATA_DIR`** environment variable in your `.env.local` file to override the default `~/.omniroute/` path. The [`runtimeEnv.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/runtimeEnv.ts) Zod schema validates this variable at startup and directs all database operations to your custom location.

### Is Docker required for local development?

No. Docker is optional and only needed if you want to test the containerized deployment mode or build multi‑arch images. The standard OmniRoute development environment runs entirely on Node.js with a local SQLite file.