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

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 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 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/).

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.

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.

npm run db:setup

This command executes 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. 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.

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) — 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:

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.

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:

docker compose up

# Or

docker run diegosouzapw/omniroute

Refer to docs/guides/DOCKER_GUIDE.md for detailed container configuration.

Electron Desktop Client

Build a native desktop application with system tray integration:

npm run electron:dev    # Development mode

npm run electron:build  # Production build

Configuration details are available in electron/README.md.

Termux Mobile Development

Run OmniRoute on Android devices without root access:

pkg install nodejs
npx -y omniroute

See docs/guides/TERMUX_GUIDE.md for mobile-specific instructions.

Remote Mode

Control a remote OmniRoute instance via scoped tokens:

omniroute connect <host>

Documentation for remote authentication is in 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 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. 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}