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

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:

• Node.js ≥22 <23 or ≥24 <27 – The runtime constraint is enforced in the engines field of 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:

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

After installation, verify code integrity:

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:

npm run db:setup

This executes 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. Create a .env.local file at the repository root to override defaults:

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

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, 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:

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:

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 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, TERMUX_GUIDE.md).

Summary

• Install Node.js ≥22 to satisfy the engine constraints in package.json.
• Run npm ci followed by npm run db:setup to initialize the 110 SQLite migrations via src/lib/db/migrationRunner.ts.
• Configure .env.local using the Zod schema in 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) 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. 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) 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.

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