OmniRoute Node.js Version Requirements: Complete Compatibility Guide

OmniRoute requires Node.js 22.22.2 or higher (LTS), explicitly excludes version 23.x, and supports Node.js 24 through 26.x across its core server, Electron client, and Opencode packages.

OmniRoute is a multi-package routing platform with strict Node.js runtime requirements defined in each component's package.json. Understanding these Node.js version requirements ensures your development environment and deployment pipelines remain compatible with the framework's engine constraints.

Core Server and CLI Node.js Requirements

The OmniRoute core server and CLI tools enforce a precise Node.js version range in the root package.json:

// package.json
{
  "engines": {
    "node": ">=22.22.2 <23 || >=24.0.0 <27"
  }
}

This specification, found at release/v3.8.51/package.json#L63, establishes:

• Minimum supported: Node.js 22.22.2 (LTS)
• Explicitly excluded: Node.js 23.x series
• Secondary range: Node.js 24.0.0 through 26.x

The exclusion of Node.js 23.x reflects this version's non-LTS status, reducing maintenance burden and runtime instability risks.

Electron Desktop Client Requirements

The Electron desktop client mirrors the core server's Node.js version requirements exactly. In electron/package.json#L13, the same engines.node field appears:

// electron/package.json
{
  "engines": {
    "node": ">=22.22.2 <23 || >=24.0.0 <27"
  }
}

This alignment ensures consistent behavior between the server-side logic and the packaged desktop application, eliminating Electron-specific runtime incompatibilities.

Opencode Provider and Plugin Requirements

The Opencode provider and plugin packages introduce slightly stricter minimums while maintaining the same upper bounds:

Package	File Path	Node.js Requirement
Opencode provider	@omniroute/opencode-provider/package.json#L49	>=22.22.3
Opencode plugin	@omniroute/opencode-plugin/package.json#L52	>=22.22.3

Both packages omit the explicit upper bound but inherit the repository's tested compatibility ceiling through peer dependency resolution and CI validation.

Programmatic Version Verification

Enforce Node.js version requirements in your CI pipelines or startup scripts using this pattern:

// utils/checkNodeVersion.js
const { engines } = require('../package.json');
const required = engines.node;                // ">=22.22.2 <23 || >=24.0.0 <27"
const semver = require('semver');

if (!semver.satisfies(process.version, required)) {
  console.error(
    `Node.js version ${process.version} is not supported. ` +
    `Required: ${required}`
  );
  process.exit(1);
}

Integrate this check into GitHub Actions workflows:

# .github/workflows/ci.yml (excerpt)

steps:
  - name: Verify Node version
    run: node utils/checkNodeVersion.js

This approach replicates npm's native engines enforcement while providing explicit failure messages for debugging.

Why OmniRoute Excludes Node.js 23.x

Node.js follows an alternating LTS release cadence where:

• Even-numbered versions (20, 22, 24, 26) receive long-term support
• Odd-numbered versions (21, 23, 25) serve as short-lived testing grounds

By excluding Node.js 23.x from its supported matrix, OmniRoute eliminates:

• Security patches that expire six months post-release
• API instability requiring frequent compatibility shims
• Dependency conflicts with native modules lacking 23.x binaries

This policy aligns with Node.js's own release working group recommendations for production deployments.

Version Requirement Summary by Component

Component	Minimum Version	Maximum Version	Source File
Core server & CLI	22.22.2	22.x or 24.x–26.x	package.json
Electron client	22.22.2	22.x or 24.x–26.x	electron/package.json
Opencode provider	22.22.3	None specified	@omniroute/opencode-provider/package.json
Opencode plugin	22.22.3	None specified	@omniroute/opencode-plugin/package.json

All components fundamentally target the Node.js 22 LTS and Node.js 24–26 LTS series as their validated runtime environment.

Summary

• Primary requirement: Node.js 22.22.2 LTS or Node.js 24.0.0 through 26.x
• Excluded version: Node.js 23.x is explicitly unsupported across all OmniRoute packages
• Stricter subpackages: Opencode provider and plugin require minimum 22.22.3
• Verification method: Use semver.satisfies() against engines.node in package.json
• Source of truth: Root package.json, electron/package.json, and scoped package manifests in @omniroute/*

Frequently Asked Questions

What happens if I run OmniRoute on Node.js 23.x?

Your package manager will emit an EBADENGINE warning during installation, and runtime behavior becomes undefined. Native dependencies may fail to compile, and OmniRoute's internal APIs may reference V8 features unstable in the 23.x series. Deployments on 23.x are explicitly unsupported.

Can I use Node.js 22.22.0 or 22.22.1 instead of 22.22.2?

No. The patch-level minimums (22.22.2 for core, 22.22.3 for Opencode packages) reflect specific security fixes and backported features that OmniRoute's dependency tree requires. Earlier 22.x patches will fail engines validation.

Does OmniRoute support Node.js 18 or 20 LTS?

No. The >=22.22.2 lower bound eliminates these older LTS lines. OmniRoute likely uses Node.js 22-specific features such as the improved fetch implementation, WebSocket client, or import.meta.dirname that remain unavailable in Node.js 20.

How do I pin Node.js version in Docker for OmniRoute?

Use an explicit LTS tag in your Dockerfile that satisfies the engines range:

FROM node:22.22.2-alpine

# or

FROM node:24.0.0-alpine

Avoid node:latest or node:current tags, as these may resolve to Node.js 23.x during that release's availability window.

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