# OmniRoute Runtime Requirements: Complete Node Version, Port, and Memory Configuration Guide

> Master OmniRoute runtime requirements. Learn Node.js versions, port 20128, native binary needs, and memory configuration for seamless operation.

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

---

**OmniRoute requires Node.js versions 22 (≥22 <23) or 24–26 (≥24 <27), runs on port 20128 by default, needs the `better-sqlite3` native binary, and enforces minimum memory settings via environment variables.**

OmniRoute is a Node-based unified AI proxy and router that enforces strict **runtime requirements** at startup. This guide breaks down every dependency, port configuration, and environment variable you need to deploy the system correctly, based on the official source code in the `diegosouzapw/OmniRoute` repository.

---

## Node.js Version Requirements

OmniRoute validates your Node runtime version immediately on startup. The platform supports two distinct version ranges and rejects anything outside them.

| Supported Range | Status |
|-----------------|--------|
| **Node ≥22 <23** | Primary LTS track |
| **Node ≥24 <27** | Current development track |

According to the [Russian README documentation](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/docs/i18n/ru/README.md), the runtime explicitly checks this range and exits with an error if your version falls outside these bounds.

Verify your installation before starting:

```bash
node -v

# Expected: v22.x.x or v24.x.x–v26.x.x

```

---

## Default Port Configuration

The **primary port** for OmniRoute is hardcoded to **20128** in [`src/lib/runtime/ports.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/runtime/ports.ts). This single port serves both the Dashboard UI and the API by default.

### Optional Port Splitting

You can separate traffic across dedicated ports using these environment variables:

| Variable | Purpose |
|----------|---------|
| `API_PORT` | Dedicated port for REST API endpoints |
| `DASHBOARD_PORT` | Dedicated port for the web Dashboard UI |
| `OMNIROUTE_PORT` | Override that takes precedence over `PORT` |

See [[`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/docs/reference/ENVIRONMENT.md#port) for the full port variable reference.

Start with a custom port:

```bash
PORT=3000 omniroute serve

```

---

## Native Binary Dependency: better-sqlite3

OmniRoute requires the **`better-sqlite3`** native module for SQLite database access. This is not an optional dependency—the `omniroute doctor` health command explicitly verifies its presence and will fail if the binary is missing or incompatible with your Node version.

The health check implementation is documented in [[`skills/cli-serve/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/skills/cli-serve/SKILL.md)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/skills/cli-serve/SKILL.md#checks-performed), which lists native binary validation as a core startup requirement.

Run the built-in diagnostic:

```bash
omniroute doctor

```

Expected output:

```

✔ Port availability
✔ Node runtime
✔ Native binary (better-sqlite3)
✔ Database connection
✔ Memory & liveness

```

---

## Memory Allocation and Limits

OmniRoute auto-configures its V8 heap based on available host resources, with specific defaults and bounds.

### Default Behavior

- **Docker images**: Preconfigured with **1024 MiB** V8 heap
- **Auto-calibration**: Runtime sets heap to approximately **35% of host RAM**
- **Clamped range**: Minimum **512 MiB**, maximum **4096 MiB**

### Manual Override

Force a specific memory allocation via [`OMNIROUTE_MEMORY_MB`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/docs/reference/ENVIRONMENT.md#omniroute_memory_mb):

```bash
OMNIROUTE_MEMORY_MB=2048 omniroute serve

```

This overrides the automatic calculation entirely.

---

## Required Secrets and Environment Variables

Before starting OmniRoute, you must generate and configure two critical secrets. The runtime reads these from `.env` at startup.

| Secret | Generation Command | Source File |
|--------|-------------------|-------------|
| `JWT_SECRET` | `openssl rand -base64 48` | [`.env.example`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/.env.example) |
| `API_KEY_SECRET` | `openssl rand -base64 48` | Same as above |

Example `.env` configuration:

```bash
JWT_SECRET=your-base64-generated-secret-here
API_KEY_SECRET=another-base64-generated-secret-here

```

The application will fail to start if either secret is missing or too short.

---

## Plugin Directory and Runtime Scanning

OmniRoute discovers plugins at runtime from a configurable directory path.

| Variable | Default Path | Description |
|----------|-------------|-------------|
| `OMNIROUTE_PLUGINS_DIR` | `~/.omniroute/plugins` | Location scanned for plugin loading |

Set a custom plugin directory:

```bash
OMNIROUTE_PLUGINS_DIR=/opt/omniroute/plugins omniroute serve

```

---

## Feature Flags and Runtime Settings

Certain **runtime requirements** can be toggled without restarting the process. Settings like `OMNIROUTE_ENABLE_RUNTIME_BACKGROUND_TASKS` are persisted in the database and apply immediately after change.

These feature flags are documented in [[`docs/reference/FEATURE_FLAGS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/FEATURE_FLAGS.md)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/docs/reference/FEATURE_FLAGS.md) and can be queried via the runtime API:

```bash
curl http://localhost:20128/api/runtime/settings

```

The endpoint returns active values for `OMNIROUTE_MEMORY_MB`, `OMNIROUTE_PLUGINS_DIR`, and enabled feature flags.

---

## Key Source Files Reference

| File Path | Purpose |
|-----------|---------|
| [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md) | Complete environment variable catalog |
| [`src/lib/runtime/ports.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/runtime/ports.ts) | Port default (20128) and splitting logic |
| [`docs/reference/CLI-TOOLS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/CLI-TOOLS.md) | `omniroute doctor` command documentation |
| [`skills/cli-serve/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/skills/cli-serve/SKILL.md) | Health check implementation details |
| `.env.example` | Template for required secrets |
| [`docs/i18n/ru/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/i18n/ru/README.md) | Node version matrix and constraints |

---

## Summary

- **Node.js versions 22 (≥22 <23) or 24–26 (≥24 <27)** are strictly enforced at startup
- **Port 20128** is the default; split traffic with `API_PORT`, `DASHBOARD_PORT`, or `OMNIROUTE_PORT`
- **`better-sqlite3` native binary** is mandatory; verify with `omniroute doctor`
- **Memory auto-calibrates** to ~35% of host RAM (512–4096 MiB range), override with `OMNIROUTE_MEMORY_MB`
- **`JWT_SECRET` and `API_KEY_SECRET`** must be generated and configured before first run
- **Plugin directory** defaults to `~/.omniroute/plugins`, customizable via `OMNIROUTE_PLUGINS_DIR`

---

## Frequently Asked Questions

### What happens if I run OmniRoute with an unsupported Node version?

The runtime performs a version check at startup and exits immediately with an error if your Node version falls outside the supported ranges (22.x or 24.x–26.x). This validation is documented in the Russian internationalization README and enforced in the core startup sequence.

### Can I run the Dashboard and API on separate ports?

Yes. While both services default to port 20128, you can set `API_PORT` and `DASHBOARD_PORT` environment variables to split traffic. Alternatively, use `OMNIROUTE_PORT` as a global override that takes precedence over the default `PORT` variable.

### How do I verify that all runtime requirements are satisfied?

Run `omniroute doctor` from the command line. This performs five checks: port availability, Node runtime version, native binary presence (better-sqlite3), database connectivity, and memory configuration. All checks must pass for the system to operate correctly.