Installation - SoulForge

Install

macOS / Linux
Windows

brew tap proxysoul/tap && brew install soulforge

Neovim and a Nerd Font are auto-installed on first launch.

Download soulforge-<version>-windows-x64.zip (portable) or soulforge-setup-<version>-x64.exe (setup wizard) from the latest release.

Portable ZIP: extract anywhere and run soulforge.exe. Keep the deps/ folder next to the executable.
Setup wizard: double-click. Per-user install to %LOCALAPPDATA%\Programs\SoulForge, no UAC prompt, registers in Settings → Apps.

Requires Windows 10 1809+ or Windows 11 (x64). ARM64 is not supported yet. SmartScreen may warn on first run — click More info → Run anyway.

Other install methods

Prebuilt binary
Bun / npm
Source

# macOS / Linux
tar xzf soulforge-*.tar.gz && cd soulforge-*/ && ./install.sh

Windows: download soulforge-<version>-windows-x64.zip, unzip anywhere, run soulforge.exe.

Requires Bun >= 1.3.13 or Node 20+.

bun install -g @proxysoul/soulforge
# or
npm install -g @proxysoul/soulforge

git clone https://github.com/proxysoul/soulforge.git
cd soulforge && bun install && bun run dev

Windows notes

SoulForge stores config + data under %LOCALAPPDATA%\SoulForge. Secrets are DPAPI-encrypted (crypt32.dll, user-scoped). A couple of features are off by default on Windows:

Embedded floating terminal panel — disabled (ghostty-opentui native addon has no stable win32 build). Override with SOULFORGE_ENABLE_GHOSTTY=1 if you’ve patched it locally.
Kitty graphics image preview — disabled (Windows Terminal + ConPTY don’t speak the protocol). Half-block art still works.
glob tool find fallback — install fd (winget install sharkdp.fd) for full glob support.

Everything else — all 21 providers, every tool, LSP, Soul Map, sessions, checkpoints, memory, MCP, themes, headless mode — works identically across macOS, Linux, and Windows.

Add a key

You need at least one LLM provider key. Pick one path:

LLM Gateway — one key for Claude, GPT, Gemini, Grok, Llama, Qwen, and others. Up to 30% off frontier models.

soulforge --set-key llmgateway sk-...

soulforge --set-key openrouter sk-or-...

Get a key at openrouter.ai.

soulforge --set-key anthropic sk-ant-...

Get a key at console.anthropic.com.

soulforge --set-key openai sk-...

Get a key at platform.openai.com.

Run Ollama or LM Studio locally — no key needed.

brew install ollama && ollama pull llama3.3

SoulForge auto-detects it on launch.

Use your existing Copilot subscription.

# after signing in via VS Code:
soulforge --set-key copilot $(jq -r '.["github.com"].oauth_token' \
  ~/.config/github-copilot/apps.json)

See Copilot setup for the full guide.

Keys are stored in your OS keychain: macOS Keychain, Linux secret-tool (libsecret), Windows DPAPI (crypt32.dll, user-scoped, at %LOCALAPPDATA%\SoulForge\secrets.dat). You can also export ANTHROPIC_API_KEY=... in your shell profile. See all 21 providers →

Launch

soulforge

Press Ctrl+L to switch models. Type /help for commands.

Next: Quickstart

Five minutes to your first refactor.

​Install

​Windows notes

​Add a key

​Launch

Next: Quickstart

Install

Windows notes

Add a key

Launch