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

> Set up your OmniRoute development environment quickly. Follow this guide to install Node.js, clone the repo, set up the database, and start the dev server easily.

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

---

**You can set up an OmniRoute development environment by installing Node.js ≥22, cloning the repository, running `npm install`, executing `npm run db:setup` to initialize the SQLite database, and starting 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. Setting up a local development environment requires configuring the runtime, initializing the database schema, and launching the multi‑layer architecture that comprises the API, dashboard, and SSE core. This guide walks you through the precise steps validated against the `diegosouzapw/OmniRoute` source code.

## Prerequisites

Before cloning the repository, ensure your system meets the following requirements defined in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json):

- **Node.js ≥22 <23 or ≥24 <27** – The runtime constraint is enforced in the `engines` field of [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) to ensure compatibility with the Next.js server and TypeScript compiler.
- **Git** – Required for cloning and submodule synchronization.
- **Python 3** (optional) – Needed only if specific native dependencies require compilation during installation.
- **Docker** (optional) – Enables containerized development modes via `docker compose` or standalone images.

## Clone and Install Dependencies

Clone the repository and install dependencies using a clean install to respect the exact lockfile versions:

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

```

After installation, verify code integrity:

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

```

## Initialize the SQLite Database

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

Run the database setup command:

```bash
npm run db:setup

```

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

## 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 defaults:

```bash

# .env.local

PORT=20128
OMNIROUTE_DATA_DIR=/custom/path
REQUIRE_API_KEY=false
OMNIROUTE_BASE_PATH=

```

Key variables include:
- **`PORT`** – HTTP port for the Next.js server and dashboard (default: `20128`).
- **`OMNIROUTE_DATA_DIR`** – Custom path for the SQLite storage directory.
- **`REQUIRE_API_KEY`** – Toggle API‑key enforcement for public routes.
- **`OMNIROUTE_BASE_PATH`** – Serve OmniRoute under a sub‑path (e.g., `/omniroute/`).

## Start the Development Server

Launch the full-stack application:

```bash
npm run dev

```

This command simultaneously initializes three architectural layers:
- **API & Routing Layer** – Exposes OpenAI‑compatible endpoints at `/v1/*` via `src/app/api/v1/*/route.ts` files.
- **Dashboard** – Serves the web UI at `http://localhost:20128/dashboard` from `src/app/(dashboard)/dashboard/*`.
- **SSE Core** – Runs the streaming request handler in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts), which manages provider translation, auto‑combo routing, and guardrail enforcement.

You can now route requests through OmniRoute at `http://localhost:20128/v1`.

## Verify Your Setup

Confirm the API is responding correctly:

```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 and auto‑combo aliases with HTTP 200.

## 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

```

Run `npm run check` to execute linting and testing before committing changes.

## Optional Development Modes

Depending on your target deployment, you can run OmniRoute in additional modes:

| Mode | Command | Entry Point |
|------|---------|-------------|
| **Docker** | `docker compose up` | Containerized Next.js server using the `Dockerfile` |
| **Electron Desktop** | `npm run electron:dev` | Native desktop window via [`electron/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/electron/README.md) setup |
| **Termux (Android)** | `pkg install nodejs && npx -y omniroute` | Mobile execution without root access |
| **Remote Mode** | `omniroute connect <host>` | CLI control of remote instances via scoped tokens |

Each mode is documented in `docs/guides/` (e.g., [`DOCKER_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/DOCKER_GUIDE.md), [`TERMUX_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/TERMUX_GUIDE.md)).

## Summary

- **Install Node.js ≥22** to satisfy the engine constraints in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json).
- **Run `npm ci`** followed by **`npm run db:setup`** to initialize the 110 SQLite migrations via [`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts).
- **Configure `.env.local`** using the Zod schema in [`src/lib/env/runtimeEnv.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/env/runtimeEnv.ts) to set `PORT`, `OMNIROUTE_DATA_DIR`, and authentication options.
- **Launch with `npm run dev`** to start the API (`src/app/api/v1/`), dashboard, and SSE core ([`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)) on port 20128.
- **Verify** functionality with a `curl` request to `/v1/models` before developing.

## Frequently Asked Questions

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

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). This version range ensures compatibility with Next.js 16 and the TypeScript compilation pipeline used by the routing and SSE layers.

### Where does OmniRoute store its SQLite database?

By default, OmniRoute creates `storage.sqlite` in the `~/.omniroute/` directory. You can customize this location by setting the **`OMNIROUTE_DATA_DIR`** environment variable in your `.env.local` file before running `npm run db:setup`.

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

Run **`npm run db:reset`** to drop and recreate the SQLite file. This command invokes the same migration runner ([`src/lib/db/migrationRunner.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrationRunner.ts)) used during setup, ensuring a clean schema with all 110 migrations applied.

### Can I run OmniRoute without Docker?

Yes. The standard development workflow uses **Node.js directly** with `npm run dev`. Docker is optional and only required if you specifically want to test the containerized deployment mode or run the standalone image `diegosouzapw/omniroute` on different architectures.