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

> Discover OmniRoute prerequisites: Node.js, npm/pnpm, SQLite, Git, and a configured .env file. Get your AI proxy/router setup with this essential guide.

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

---

**To run OmniRoute, you need Node.js ≥22 (or ≥24<27), npm ≥10 or pnpm, SQLite 3, Git ≥2.30, and a properly configured `.env` file with `DATA_DIR` and provider API keys.**

OmniRoute by diegosouzapw is a sophisticated AI-proxy and request router built on modern TypeScript and Next.js 16. Before you can build, run, or extend the system, you must satisfy several system-level and project-level prerequisites ranging from runtime versions to database persistence. This guide details every requirement using specific file paths and commands directly from the source repository.

## Core System Requirements

### Node.js Runtime

OmniRoute requires **Node.js ≥22<23 or ≥24<27**, as enforced by the build system and specified in the **Build & Run** section of the main README. This constraint exists because the entire stack—including the **Open-SSE** workspace (`open-sse/`) and Next.js 16 App Router—relies on modern ECMAScript modules and TypeScript 6.0 features. The core request handling pipeline in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) assumes a modern JavaScript engine that only these Node versions provide.

### Package Manager

You must use **npm (v10+)** or **pnpm**. The repository ships with a [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json) (pnpm is supported but not the primary lockfile). This ensures deterministic installation of approximately 600 dependencies. Attempting to run `npm install` with an outdated npm version will fail during the dependency resolution phase.

### SQLite 3 Database

**SQLite 3** is mandatory for the persistence layer. At runtime, OmniRoute creates a SQLite database at `~/.omniroute/omniroute.db` (or the path specified by `DATA_DIR`). The singleton instance is initialized in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts), which requires a writable filesystem location. All domain modules—including provider catalogs, combo configs, and usage statistics—depend on this **better-sqlite3** integration.

### Git Version Control

**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 deployment scripts rely on Git metadata to verify the repository state.

## Optional Infrastructure Components

### Docker for Self-Hosted Providers

**Docker ≥24** (or a compatible OCI runtime) is optional but required if you plan to run self-hosted models such as **LM Studio**, **vLLM**, or **Oobabooga**. These providers are launched via the `docker` provider interface. Without Docker, you can still use OmniRoute with cloud APIs like OpenAI or Anthropic.

### Python 3.11+ for Plugins

**Python 3.11+** is optional and only needed for certain plugins such as **LangFuse** or CLI-based tools. Some optional plugins ship Python scripts that the CLI invokes directly; these are not required for the core routing functionality.

### OpenSSL for TLS Handling

**OpenSSL ≥1.1.1** is used by the MITM proxy and TLS certificate management. The MITM helper in `src/mitm/cert/` generates certificates on-the-fly for local development and proxy interception. Missing OpenSSL will cause the server to abort during startup when attempting to initialize the certificate authority.

## Mandatory Environment Configuration

OmniRoute requires a **`.env` file** (or equivalent system environment variables) before the server will start. At minimum, you must define:

- **`DATA_DIR`**: Defaults to `~/.omniroute/` if unset. This path must be writable and hosts the SQLite database.
- **Provider API keys**: Depending on which providers you enable in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts), you need corresponding keys (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). The guardrails framework in `src/lib/guardrails/` will reject requests if required secrets are missing.
- **Guardrail settings**: Variables like `PII_REDACTION_ENABLED` default to safe values but should be explicitly configured.

The repository includes an `.env.example` file at the root that lists all required variables. Copy this template and fill in your credentials before running any commands.

## Development Tools (Optional)

While not strictly required for runtime, the following tools improve the development experience:

- **VS Code** or another modern IDE (referenced in [`docs/frameworks/AGENTBRIDGE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/AGENTBRIDGE.md))
- **Git LFS** if you plan to checkout large model blobs or binary assets tracked by LFS

## Step-by-Step Installation Verification

Follow these commands to verify you meet all prerequisites and start the system:

### 1. Install Node.js via nvm

```bash
nvm install && nvm use

```

This reads the `.nvmrc` file in the repository root to install the correct Node version.

### 2. Install Dependencies

```bash
npm ci

```

This installs all ~600 packages deterministically using [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json).

### 3. Configure Environment Variables

```bash
cp .env.example .env

# Edit .env to set DATA_DIR, OPENAI_API_KEY, etc.

```

See `.env.example` for the full list of required variables.

### 4. Start the Development Server

```bash
npm run dev

```

The Next.js server starts on `http://localhost:3000` and initializes the SQLite database at `$DATA_DIR/omniroute.db` (as implemented in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts)).

### 5. Verify the MCP Interface

```bash
npx omniroute --mcp

```

The CLI reads the same database and environment configuration, then prints available MCP tools documented in [`docs/frameworks/MCP-SERVER.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/MCP-SERVER.md).

### 6. Test the A2A Endpoint

```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
      }'

```

This dispatches to [`src/lib/a2a/message/send.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/a2a/message/send.ts), validating that the routing core, database, and environment are all functional.

## Summary

- **Node.js ≥22<27 or ≥24<27** is mandatory for the modern JavaScript runtime used by [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) and the Next.js 16 App Router.
- **SQLite 3** and a writable `DATA_DIR` are required for persistence; the database singleton is created in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts).
- **Git ≥2.30** and **npm ≥10** (or pnpm) are required for repository management and dependency installation.
- **Docker ≥24** and **Python 3.11+** are optional but necessary for self-hosted providers and specific plugins.
- A properly configured **`.env` file** with `DATA_DIR` and provider API keys is mandatory; the server will abort without these variables.

## Frequently Asked Questions

### What Node.js version does OmniRoute require?

OmniRoute requires Node.js ≥22 (but <23) or ≥24 (but <27). This constraint is enforced by the build system and documented in the main README, as the codebase uses ECMAScript modules and TypeScript 6.0 features that depend on modern V8 engine capabilities present only in these versions.

### Is Docker required to run OmniRoute?

No, Docker is optional. You only need Docker ≥24 if you plan to use self-hosted AI providers such as LM Studio, vLLM, or Oobabooga, which are launched via the `docker` provider interface. Cloud-based providers like OpenAI work without Docker.

### Where does OmniRoute store its database?

OmniRoute uses SQLite 3 and creates its database at `~/.omniroute/omniroute.db` by default, or at the path specified by the `DATA_DIR` environment variable. The database singleton initialization logic in [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) requires this directory to be writable.

### What happens if I don't configure the `.env` file?

The server will abort during startup. The application requires at minimum a `DATA_DIR` variable and valid API keys for any providers you enable in [`src/shared/constants/providers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts). The guardrails framework in `src/lib/guardrails/` explicitly validates the presence of these secrets and exits with an error if they are missing.