Node.js Requirements
Node.js version requirements and native module compatibility.
Required Version
ArgentOS requires Node.js 22+. Use nvm to manage versions:
nvm install 22
nvm use 22Do not use Homebrew Node on macOS. Native modules like better-sqlite3 are compiled against the Node ABI version at install time. Mixing Homebrew and nvm Node will cause MODULE_VERSION mismatch errors.
Native Module Issues
If you see NODE_MODULE_VERSION mismatch errors:
cd /path/to/argentos
pnpm rebuild better-sqlite3LaunchAgent (macOS)
The gateway LaunchAgent plist uses whatever node binary is in PATH at install time. If the plist points to Homebrew node but your modules were built against nvm node, the gateway will crash silently.
Fix: Edit ~/Library/LaunchAgents/ai.argent.gateway.plist and ensure the node path matches your nvm version:
<string>/Users/you/.nvm/versions/node/v22.22.0/bin/node</string>Then reload:
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.argent.gateway.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.argent.gateway.plist