# Prerequisites for OmniRoute: Complete Setup Guide for the AI Router

> Discover OmniRoute prerequisites. Learn about Nodejs SQLite OpenSSL and .env file configuration needed to set up this AI router.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: getting-started
- Published: 2026-07-29

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts).

For package management, use **npm v10+** (the repository ships with [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json)). While `pnpm` is supported, the lockfile guarantees deterministic installation of approximately 600 dependencies. Run the following to align your environment:

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts):

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/providerSchema.ts):

```bash
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/`:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.