Install

IsonForge runs on Node.js 18+ and works on Linux, macOS, WSL, and native Windows.

Linux / macOS / WSL:

curl -fsSL https://www.isonai.net/install-forge | bash

Windows PowerShell:

irm https://www.isonai.net/install-forge.ps1 | iex

What the installer does:

  1. Detects your OS + checks for Node.js 18+.
  2. Installs Node 20 LTS via your OS package manager (Linux: apt/dnf/pacman/apk; macOS: Homebrew; Windows: winget) if missing.
  3. Downloads the IsonForge tarball from https://www.isonai.net/forge/cli-latest.tar.gz.
  4. Verifies SHA256 against the version pinned in the installer.
  5. Extracts to ~/.isonforge/cli/ and runs npm install --omit=dev.
  6. Writes a launcher wrapper to ~/.local/bin/isonforge (Linux/macOS) or %LOCALAPPDATA%\Microsoft\WindowsApps\isonforge.cmd (Windows).
  7. Adds ~/.local/bin to your shell PATH (Linux/macOS) by appending to ~/.bashrc / ~/.zshrc / ~/.config/fish/config.fish.

After install, restart your shell (or open a new terminal window) so PATH refreshes.

Verify

isonforge --version
isonforge auth status

Update

In a running session:

/upgrade

This downloads the latest tarball, verifies the new SHA, and self-restarts the CLI. The wrapper installer handles restart via exit code 99.

Outside a session:

isonforge update          # alias - re-runs the network installer

Or just re-run the one-line install command.

Uninstall

rm -rf ~/.isonforge
rm -f ~/.local/bin/isonforge   # Linux / macOS

On Windows:

Remove-Item -Recurse $env:USERPROFILE\.isonforge
Remove-Item $env:LOCALAPPDATA\Microsoft\WindowsApps\isonforge.cmd

Node.js itself is left installed (you may use it for other tools).

Manual install (offline / restricted networks)

  1. Download cli-latest.tar.gz from https://www.isonai.net/forge/cli-latest.tar.gz.
  2. Verify with the matching .sha256 at https://www.isonai.net/forge/cli-latest.tar.gz.sha256.
  3. Extract to ~/.isonforge/cli/.
  4. cd ~/.isonforge/cli && npm install --omit=dev.
  5. Symlink or wrapper-script bin/isonforge.js into your PATH.

Where files live

Path What
~/.isonforge/cli/ CLI source + node_modules
~/.isonforge/config.json API key + endpoint
~/.isonforge/sessions/<id>.json Saved conversations
~/.isonforge/agents/<id>/ Background agent state + logs
~/.isonforge/skills/<name>/SKILL.md User Skills
~/.isonforge/settings.json User settings (hooks, MCP, defaults)
~/.isonforge/permissions.json Persistent permission rules + preset
~/.isonforge/global-memory.md #note shorthand sink
~/.isonforge/exports/ /export output
~/.isonforge/cache/ Model metadata cache

All files mode 0600 / directories 0700 where they contain credentials or private session content.

Common issues

isonforge: command not found after install. PATH didn't refresh. Open a new terminal window, or run source ~/.bashrc (or source ~/.zshrc).

Windows: "npm.ps1 cannot be loaded because running scripts is disabled". PowerShell execution policy blocks .ps1 scripts. IsonForge's own installer uses npm.cmd internally to avoid this, but if you see it in another context: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

SHA256 mismatch during install. Either the tarball was tampered with in transit (rare on HTTPS) or the installer is stale. Re-run the install command - it always fetches the matching SHA pin.

More: Troubleshooting.