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

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 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 (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, 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, 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)
• 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

nvm install && nvm use

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

2. Install Dependencies

npm ci

This installs all ~600 packages deterministically using package-lock.json.

3. Configure Environment Variables

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

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

5. Verify the MCP Interface

npx omniroute --mcp

The CLI reads the same database and environment configuration, then prints available MCP tools documented in docs/frameworks/MCP-SERVER.md.

6. Test the A2A Endpoint

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, 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 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.
• 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 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. The guardrails framework in src/lib/guardrails/ explicitly validates the presence of these secrets and exits with an error if they are missing.

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