How to Set Up an OmniRoute Development Environment: Complete Guide

To set up an OmniRoute development environment, clone the repository, install Node.js ≥22, run npm ci to install dependencies, initialize the SQLite database with npm run db:setup, and start 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 SQLite. Whether you are contributing to the auto-combo routing engine or testing the SSE translation core, this guide walks you through the exact steps to configure your local development stack according to the official source code.

Prerequisites

Before installing OmniRoute, ensure your system meets the following requirements:

• Node.js ≥22 <23 or ≥24 <27 (specified in package.json engines)
• Git for cloning the repository
• Python 3 (optional) for compiling native SQLite bindings
• Docker (optional) for running containerized development modes
• Electron build tools (optional) when building the desktop client

These requirements ensure compatibility with the Next.js server and the native dependencies used by the persistence layer.

Clone and Install Dependencies

Start by cloning the repository and installing the Node packages:

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

The npm ci command performs a clean install based on the package-lock.json, guaranteeing reproducible builds across environments. After installation, verify code quality:

npm run lint
npm run typecheck:core

Initialize the SQLite Database

OmniRoute persists 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 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 set up your local database schema.

Configure Environment Variables

OmniRoute validates its runtime environment through a Zod schema defined in src/lib/env/runtimeEnv.ts. Create a .env.local file in the repository root to override any defaults:

Variable	Description	Default
PORT	HTTP port for the Next.js server	20128
OMNIROUTE_DATA_DIR	Custom path for SQLite storage	~/.omniroute/
REQUIRE_API_KEY	Toggle API-key enforcement	false
OMNIROUTE_BASE_PATH	Serve under a sub-path	none

Launch the Development Server

Start the full-stack development environment:

npm run dev

When you run this command, the following services start simultaneously on port 20128:

• API routes (src/app/api/v1/*) expose the OpenAI-compatible endpoint at /v1/*
• Dashboard pages (src/app/(dashboard)/dashboard/*) serve the web UI at http://localhost:20128/dashboard
• SSE core (open-sse/handlers/chatCore.ts) processes streaming requests, handles provider translation, and manages auto-combo routing

Verify Your Setup

Confirm your environment is running correctly with a quick health check:

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

You should receive a JSON list of registered models. A 200 OK response indicates your OmniRoute development environment is ready for use.

Optional Development Modes

OmniRoute supports several alternative runtime modes for specific use cases:

Docker Development

Run the full stack in a containerized environment:

docker compose up

Or use the pre-built image: docker run diegosouzapw/omniroute. Configuration details are available in docs/guides/DOCKER_GUIDE.md.

Electron Desktop Client

Build the native desktop application with system tray support:

npm run electron:dev
npm run electron:build

Refer to electron/README.md for build-specific requirements.

Termux (Android)

Run OmniRoute on mobile devices without root access:

pkg install nodejs
npx -y omniroute

See docs/guides/TERMUX_GUIDE.md for the complete mobile setup.

Remote Mode

Control a remote OmniRoute instance via scoped tokens:

omniroute connect <host>

Documentation is available in docs/guides/REMOTE-MODE.md.

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

Always run npm run check (lint + tests) before committing changes to ensure code quality.

Common Development Tasks

Add a New Provider Connection

curl -X POST http://localhost:20128/api/providers \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "name": "my-openai",
    "authType": "apiKey",
    "apiKey": "sk-xxxx"
  }'

This endpoint is implemented in src/app/api/providers/create/route.ts.

Execute a Streaming Chat Request

curl -N -X POST http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/coding",
    "messages": [{"role": "user", "content": "Write a quicksort in Python."}],
    "stream": true
  }'

The request flows through src/app/api/v1/chat/completions/route.ts to the core handler in open-sse/handlers/chatCore.ts, which manages translation and executor dispatch via open-sse/executors/default.ts.

Enable Guardrails (PII Masking)

curl -X PUT http://localhost:20128/api/settings/guardrails \
  -H "Content-Type: application/json" \
  -d '{"piiMasking": true}'

Guardrail logic resides in src/lib/guardrails/ and is wired into the request pipeline through src/middleware/promptInjectionGuard.ts.

Summary

Setting up an OmniRoute development environment requires these key steps:

• Install Node.js ≥22 and run npm ci to install dependencies
• Initialize the SQLite database using npm run db:setup, which runs src/lib/db/migrationRunner.ts
• Configure environment variables in .env.local (validated by src/lib/env/runtimeEnv.ts)
• Start the dev server with npm run dev to launch the API, dashboard, and SSE core on port 20128
• Verify the setup with a curl request to http://localhost:20128/v1/models
• Run the full test suite with npm run test:all before submitting changes

Frequently Asked Questions

What Node.js version is required for OmniRoute development?

OmniRoute requires Node.js ≥22 <23 or ≥24 <27, as specified in the package.json engines field. This ensures compatibility with the Next.js 16 server and TypeScript compilation processes.

How do I reset the SQLite database during development?

Run npm run db:reset to drop and recreate the SQLite file. This command clears all provider connections, combos, and usage logs while re-applying the 110 schema migrations from db/migrations/.

Can I run OmniRoute without installing Node.js locally?

Yes. You can run OmniRoute in Docker using docker compose up or the pre-built image diegosouzapw/omniroute. For mobile development, use Termux on Android to install Node.js and run npx -y omniroute without a traditional desktop environment.

How do I enable API key authentication in development?

Set REQUIRE_API_KEY=true in your .env.local file. This variable is validated by the Zod schema in src/lib/env/runtimeEnv.ts and enforces API-key authentication on public routes when running npm run dev.

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