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

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

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:

npm ci
npm run lint
npm run typecheck:core

The npm ci command guarantees reproducible builds by honoring 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:

npm run db:setup

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

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

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

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

Remote Mode — Control a remote OmniRoute instance using scoped tokens with omniroute connect <host>. See 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:

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.
• Configure custom paths and security settings via environment variables validated in 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 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 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 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.

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