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

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, the runtime explicitly checks this range and exits with an error if your version falls outside these bounds.

Verify your installation before starting:

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. 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/release/v3.8.51/docs/reference/ENVIRONMENT.md#port) for the full port variable reference.

Start with a custom port:

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

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:

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
API_KEY_SECRET	openssl rand -base64 48	Same as above

Example .env configuration:

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:

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/release/v3.8.51/docs/reference/FEATURE_FLAGS.md) and can be queried via the runtime API:

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	Complete environment variable catalog
src/lib/runtime/ports.ts	Port default (20128) and splitting logic
docs/reference/CLI-TOOLS.md	omniroute doctor command documentation
skills/cli-serve/SKILL.md	Health check implementation details
.env.example	Template for required secrets
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.

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