xNode Manager

What is xNode Manager?

xNode Manager (xnode) is a production-grade Node.js version management system designed for Linux environments. It uses a shim architecture to dynamically route node, npm, and npx commands to the correct version based on a hierarchical configuration — no shell restarts, no manual PATH juggling.

Think of it as a self-hosted, server-grade alternative to nvm or fnm — built for real production Linux systems, not just developer laptops.

Why Not Just Use nvm?

nvm is a shell function. It mutates your shell environment, requires re-sourcing on every new shell, and doesn’t work well with system services, cron jobs, or Docker entrypoints. xnode solves this by replacing the actual node, npm, and npx binaries with lightweight Go shim binaries that resolve the correct version at runtime — no shell state required.

How It Works

Hierarchical Resolution

xnode resolves the Node.js version using a strict priority chain:

Project (.xcloud-node file)
  └── User (~/.xcloud-node)
        └── Global (/etc/xnode/node.default)

The shim checks each level in order and routes to the matching installed version — automatically, every time.

Shim Architecture

Two binaries make up the system:

• xnode — The manager CLI. Install, remove, set, list, and maintain versions.
• shim — A lightweight proxy placed at /usr/local/bin/node (and symlinked to npm/npx). It resolves the correct version and execs into it transparently.

Zero overhead. No wrappers. Just a fast Go binary making a single decision.

Key Features

Version Management

xnode install 22        # Install latest LTS for v22
xnode install 20.9.0    # Install specific patch version
xnode set-global 22     # Set global default
xnode set-user 20       # Set per-user default
xnode list              # List all installed versions
xnode delete 18.0.0     # Remove a version

Project-Specific Versions

cd /path/to/project
echo "18" > .xcloud-node
node --version  # → v18.x.x (automatic)

Security — SHA256 Integrity Verification

Every downloaded Node.js binary is verified against its official SHA256 checksum before installation. Tampered or corrupted downloads are rejected.

xnode verify   # Re-verify all installed binaries

Health Checks — doctor

Detects ABI/architecture mismatches in node_modules after version switches. Prevents silent runtime failures when switching major versions.

xnode doctor

Maintenance Commands

xnode prune                       # Remove unused versions
xnode migrate --from 18 --to 22   # Migrate global packages between versions
xnode check-service /path/to/app  # Pre-flight check before starting a service

Installation

Build from Source

git clone https://github.com/reduanmasud/xnode-manager
cd xnode-manager
go mod tidy
mkdir -p bin
go build -o bin/xnode cmd/xnode/main.go
go build -o bin/shim cmd/shim/main.go

System Setup

# Install directories
sudo mkdir -p /opt/xnode/versions
sudo chown -R $USER:$USER /opt/xnode

# Config
sudo mkdir -p /etc/xnode
sudo touch /etc/xnode/node.default
sudo chmod 666 /etc/xnode/node.default

# Deploy shim as the system node binary
sudo cp bin/shim /usr/local/bin/node
sudo ln -sf /usr/local/bin/node /usr/local/bin/npm
sudo ln -sf /usr/local/bin/node /usr/local/bin/npx

Tech Stack

• Go — Single-binary builds, fast startup, no runtime dependencies
• Linux — ARM64 and AMD64 supported
• SHA256 — Official Node.js SHASUMS for integrity verification
• /etc/xnode — System-level configuration for multi-user environments

What’s Next

• Auto-detection of .nvmrc and .node-version files for compatibility
• Daemon mode with file-watch triggers for automatic version switching
• RPM/DEB packages for easier system installation
• Web dashboard for managing versions across a fleet of servers