INSTALL

Step 1 of 3

Welcome, builder. Before you can forge, you need the tools. Node.js 20 or later, and Claude Code installed and authenticated. That's it. Let's get you set up.

Galadriel

PREREQUISITES

✓Node.js 20+ — The runtime that powers the forge. Download from nodejs.org (LTS recommended). Verify with node --version
✓Claude Code — Anthropic's coding CLI. This is the engine that runs every agent, every command, every build phase. Install with: curl -fsSL https://claude.ai/install.sh | bash then authenticate with your Anthropic API key. See the Claude Code docs for details.
✓Git — Required for version control. Download from git-scm.com. Verify with git --version

Windows? PowerShell works. macOS or Linux? Your default terminal works. One command gets you the whole forge. No git branches, no manual cloning — just npm.

Kusanagi

QUICK START

CREATE A PROJECT

One command creates a new project with the wizard, methodology, and 264+ agent definitions — everything you need.

$ npx thevoidforge init my-app

cd my-app

claude# opens Claude Code

/build# builds the app

GLOBAL INSTALL (OPTIONAL)

Install the CLI globally for repeated use. The voidforge command becomes available everywhere.

$ npm install -g thevoidforge

$ voidforge init my-app

REMOTE ACCESS (VPS / LAN)

Installing on a remote server? The wizard UI runs on port 3141. Use LAN mode for private networks:

$ voidforge init --lan

See the Wizard tutorial for SSH tunnel, --lan, and --remote options.

npm packages: The package name is thevoidforge (CLI + wizard). The methodology (agents, commands, methods, patterns) is bundled automatically via thevoidforge-methodology.

PLATFORM-SPECIFIC INSTALLATION

MACOS

Install via Homebrew or download the LTS installer from nodejs.org.

brew install node@20

UBUNTU / DEBIAN (SERVERS, VPS, EC2)

Do NOT use apt install nodejs — Ubuntu 22.04 ships Node 12, which is 8 major versions behind the requirement. Use NodeSource instead:

# Remove conflicting system packages (if present)

sudo apt-get remove -y libnode-dev nodejs-doc

# Install Node 20 via NodeSource

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

sudo apt-get install -y nodejs

# Verify

node -v # Should show v20.x

npm -v # Should show 10.x

Common failure: If apt install nodejs fails with trying to overwrite '/usr/include/node/common.gypi', run sudo apt-get remove -y libnode-dev first, then retry the install.

WINDOWS

Download Node 20 LTS from nodejs.org. If npm install fails with node-gyp errors, either install Visual C++ Build Tools or skip this step — VoidForge projects have no native dependencies.

VERIFY YOUR TOOLS

Open your terminal and run these three commands. If any fails, install the missing tool using the links above.

$ node --version→ v20.x or higher (minimum 20.11.0)

$ git --version→ any version

$ claude --version→ Claude Code CLI

All three green? You're ready to forge. If node or git isn't found, install them using the links above and restart your terminal.

TROUBLESHOOTING

LINUX / SERVER

node-gyp errors — Native modules need build tools. Install them with: sudo apt-get install -y build-essential python3

Permission errors — Never use sudo npm install. Fix npm permissions instead:

mkdir ~/.npm-global

npm config set prefix '~/.npm-global'

# Add ~/.npm-global/bin to your PATH

EBADENGINE warnings — Your Node version is too old. Follow the NodeSource instructions above to install Node 20.

WINDOWS

PowerShell 7+ supports the && syntax in our install commands. If you're using the older Windows PowerShell 5.1, run each command separately instead of chaining with &&.

npm install fails? If you see node-gyp errors during global install, install Visual C++ Build Tools or use npx thevoidforge init instead (no global install needed).

VS Code users: Open the integrated terminal (Ctrl+`) and you're ready. Works with PowerShell, Command Prompt, Git Bash, or WSL.

For a detailed Windows walkthrough, see the Windows Quickstart Guide.