Installation

Prerequisites

Dependency	Required	Notes
Bun >= 1.0	Only for npm/Bun install method	Not needed for prebuilt binary or Homebrew
Neovim >= 0.11	Auto-installed on first launch	SoulForge offers to download it if missing
Nerd Font	Auto-installed on first launch	SoulForge offers to download one if missing
API key	At least one LLM provider	See below

API key

You need at least one LLM provider key:

Provider	Env Variable	Models
Anthropic	`ANTHROPIC_API_KEY`	Claude Opus 4, Sonnet 4, Haiku 3.5
OpenAI	`OPENAI_API_KEY`	GPT-4o, o3, o4-mini
xAI	`XAI_API_KEY`	Grok
Google	`GOOGLE_GENERATIVE_AI_API_KEY`	Gemini
Ollama	(none — runs locally)	Llama, Mistral, Qwen, etc.

Add to your shell profile (~/.zshrc or ~/.bashrc):

export ANTHROPIC_API_KEY=sk-ant-...

Or use a single AI Gateway key for all providers, or the built-in Proxy provider to relay through a local CLIProxyAPI instance (no API key needed).

Install

Prebuilt binary (recommended)
Homebrew
npm / Bun
Build from source

Download the standalone binary — no runtime dependencies:

# macOS (Apple Silicon)
curl -fsSL https://github.com/ProxySoul/soulforge/releases/latest/download/soulforge-darwin-arm64.tar.gz | tar xz
sudo mv soulforge-darwin-arm64 /usr/local/bin/soulforge

# macOS (Intel)
curl -fsSL https://github.com/ProxySoul/soulforge/releases/latest/download/soulforge-darwin-x64.tar.gz | tar xz
sudo mv soulforge-darwin-x64 /usr/local/bin/soulforge

# Linux (x64)
curl -fsSL https://github.com/ProxySoul/soulforge/releases/latest/download/soulforge-linux-x64.tar.gz | tar xz
sudo mv soulforge-linux-x64 /usr/local/bin/soulforge

# Linux (ARM64)
curl -fsSL https://github.com/ProxySoul/soulforge/releases/latest/download/soulforge-linux-arm64.tar.gz | tar xz
sudo mv soulforge-linux-arm64 /usr/local/bin/soulforge

Then run soulforge (or sf).

brew tap proxysoul/tap
brew install soulforge

Requires Bun >= 1.0 as the runtime.

# Install Bun (if needed)
curl -fsSL https://bun.sh/install | bash

# Configure GitHub Packages registry (one-time)
echo "@proxysoul:registry=https://npm.pkg.github.com" >> ~/.npmrc

# Install globally
bun install -g @proxysoul/soulforge

Requires Bun >= 1.0.

git clone https://github.com/ProxySoul/soulforge.git
cd soulforge
bun install

# Run in development mode
bun run dev

# Or build and link globally
bun run build
bun link
soulforge

First launch

On first launch, SoulForge checks for Neovim and Nerd Fonts. If either is missing, it offers to download and install them from official GitHub releases. This is optional — you can install them manually if you prefer. Run /setup anytime to re-check prerequisites.

soulforge                    # Launch -- select a model with Ctrl+L
soulforge --set-key anthropic sk-ant-...   # Or save a key first
soulforge --list-providers   # Check which providers are ready

Getting started

Core concepts

Agents

Context management

Tools

Reference

Prerequisites

API key

Install

First launch

Getting started

Core concepts

Agents

Context management

Tools

Reference

​Prerequisites

​API key

​Install

​First launch

Prerequisites

API key

Install

First launch