Prerequisites for OmniRoute: Complete Setup Guide for the AI Router

OmniRoute requires Node.js (≥22 <23 or ≥24 <27), SQLite 3, OpenSSL ≥1.1.1, and a configured .env file with DATA_DIR set to initialize the routing engine and database layer.

OmniRoute is an open-source AI proxy and router developed under diegosouzapw/OmniRoute that unifies access to large language models through a Next.js frontend and Open-SSE backend. Before you can build, run, or extend this sophisticated routing system, you must satisfy specific system-level dependencies and configuration requirements. This guide covers every prerequisite derived directly from the repository's source code, including the Electron desktop build instructions and VM deployment guides.

Core Runtime Dependencies

The OmniRoute stack is built on modern ECMAScript modules and TypeScript 6.0, requiring a specific Node.js runtime and persistent storage layer.

Node.js and Package Manager

You must install Node.js ≥22 <23 or ≥24 <27, as specified in the Build & Run section of the main README and the Electron-specific documentation at electron/README.md. The entire source tree assumes a modern JavaScript engine capable of handling the async patterns used in open-sse/handlers/chatCore.ts.

For package management, use npm v10+ (the repository ships with package-lock.json). While pnpm is supported, the lockfile guarantees deterministic installation of approximately 600 dependencies. Run the following to align your environment:

# Use the version specified in .nvmrc (or install via nvm)

nvm install && nvm use

# Install all dependencies

npm ci

SQLite 3 Database

OmniRoute uses better-sqlite3 as its persistence layer, configured in src/lib/db/core.ts. The runtime automatically creates a SQLite database at ~/.omniroute/omniroute.db (or the path specified by DATA_DIR). You need SQLite 3 available on the host system to support this operations-critical storage, which holds provider catalogs, combo configurations, and usage statistics.

Ensure the user running the application has write permissions to the target directory, as the database singleton initializes on first boot and will exit if the filesystem is read-only.

OpenSSL and Git

OpenSSL ≥1.1.1 is mandatory for the MITM proxy and TLS certificate generation handled in src/mitm/cert/. The system generates certificates on-the-fly for secure local routing, and missing OpenSSL headers will cause the bootstrap process to abort with a clear error logged by the built-in logger.

Git ≥2.30 is required for submodule handling and version-specific documentation. The build process references the current Git commit SHA (BUILD_SHA) during releases, and some documentation paths assume Git is available for path resolution.

Optional Infrastructure Components

Depending on your deployment target and provider strategy, you may need additional tooling.

Docker for Self-Hosted Providers

If you plan to run self-hosted models such as LM Studio, vLLM, or Oobabooga through the docker provider type, install Docker ≥24 or a compatible OCI runtime. The provider executors in src/shared/constants/providers.ts spawn containers dynamically, and without Docker available, these routing options will fail silently or return provider-unavailable errors.

Python 3.11+ for Plugins

Certain optional plugins and CLI tools (such as LangFuse integrations) ship Python scripts invoked via subprocess calls. Install Python 3.11+ if you intend to use these specific extensions, though the core Node.js application runs independently of the Python runtime.

Environment Configuration

OmniRoute will not start without proper environment variables. Copy the template from .env.example to .env in the project root:

cp .env.example .env

At minimum, configure:

• DATA_DIR: Defaults to ~/.omniroute/ and determines where SQLite writes its files. The path must be writable as verified in src/lib/db/core.ts.
• Provider API keys: Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or equivalents for each provider you enable in src/shared/constants/providers.ts.
• Guardrails: Variables like PII_REDACTION_ENABLED default to safe values but should be explicitly configured.

Without these variables, the server aborts during startup, and the guardrails framework (src/lib/guardrails/) will reject requests missing required secrets.

Development and Deployment Tools

For local development, VS Code is referenced in the AgentBridge guide (docs/frameworks/AGENTBRIDGE.md) for debugging the TypeScript and Next.js 16 App Router code. Git LFS is recommended only if you checkout large model blobs, but is not required for runtime operation.

When deploying to production VMs, consult docs/ops/VM_DEPLOYMENT_GUIDE.md for OS-specific package installation instructions covering SQLite, OpenSSL, and Node version management.

Step-by-Step Setup Verification

After installing prerequisites, verify your setup by initializing the development server and CLI tools.

Initialize the Development Server

Run the Next.js development server to verify Node compatibility and database initialization:

npm run dev

The server starts on http://localhost:3000 and initializes the SQLite instance at $DATA_DIR/omniroute.db. Check the console output for successful DB bootstrap messages from src/lib/db/core.ts.

Test the MCP Server Interface

Validate the Model Context Protocol (MCP) server configured in open-sse/mcp-server/server.ts:

npx omniroute --mcp

This command reads the same database and environment configuration, then prints available MCP tools. The MCP server requires both the database connection and TLS certificates generated by the MITM helper to be present before it starts listening.

Register a Provider via CLI

Confirm end-to-end functionality by adding a provider through the CLI, which updates the providers table using the Zod schema in src/shared/validation/providerSchema.ts:

omniroute provider add openai \
  --api-key $OPENAI_API_KEY \
  --model gpt-4o-mini

Test the A2A Endpoint

Verify the A2A JSON-RPC server implementation in src/lib/a2a/:

curl -X POST http://localhost:3000/a2a \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"message/send",
        "params":{"model":"gpt-4o-mini","prompt":"Hello, world!"},
        "id":1
      }'

The payload is dispatched by src/lib/a2a/message/send.ts, routing through the same core pipeline used by the HTTP API.

Summary

• Node.js ≥22 <23 or ≥24 <27 is mandatory for the modern ECMAScript and TypeScript 6.0 codebase, particularly the streaming handlers in open-sse/handlers/chatCore.ts.
• SQLite 3 and a writable DATA_DIR are required for the persistence layer managed in src/lib/db/core.ts.
• OpenSSL ≥1.1.1 enables the MITM proxy and TLS certificate generation; missing this causes immediate startup failure.
• Docker ≥24 and Python 3.11+ are optional but required for self-hosted providers and specific plugin integrations.
• The .env file must define DATA_DIR and provider API keys before the server can bootstrap the database and guardrail frameworks.

Frequently Asked Questions

What Node.js version does OmniRoute require?

OmniRoute requires Node.js versions ≥22 <23 or ≥24 <27, as enforced by the runtime checks in the Open-SSE workspace and documented in the Electron README. Using Node 20 or Node 23 specifically will likely cause compatibility issues with the async patterns and TypeScript 6.0 features used throughout open-sse/handlers/chatCore.ts.

Is Docker required to run OmniRoute?

Docker is optional and only required if you intend to route traffic to self-hosted models like vLLM or LM Studio via the docker provider type. The core routing engine, SQLite database, and Next.js frontend run entirely within the Node.js process without containerization.

Where does OmniRoute store its SQLite database?

By default, OmniRoute creates its SQLite database at ~/.omniroute/omniroute.db, though this path is configurable via the DATA_DIR environment variable. The singleton database instance is initialized in src/lib/db/core.ts and stores provider catalogs, combo configurations, and usage statistics.

What happens if I forget to set up the .env file?

Without a properly configured .env file (copied from .env.example), OmniRoute will abort during startup. The initialization sequence in the server bootstrap checks for required variables like DATA_DIR, and the guardrails framework (src/lib/guardrails/) will reject provider requests missing API keys or OAuth credentials, logging clear error messages before exiting.

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