# How to Install SwarmForge: Complete Setup Guide for AI Agent Orchestration

> Install SwarmForge quickly with our complete setup guide. Follow three simple steps to get your AI agent orchestration running today. Learn how to install SwarmForge now.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: getting-started
- Published: 2026-08-28

---

**Install SwarmForge in three steps: install prerequisites (`zsh`, `git`, `tmux`, `bb`/`babashka`, and an LLM backend), run the `get-swarm-forge` helper in your chosen workspace directory, then launch the dashboard with `./swarm`.**

SwarmForge is a **tmux-based orchestration platform** for AI-agent swarms developed by Robert C. Martin (Uncle Bob). This guide walks through the complete SwarmForge installation process using the official `unclebob/swarm-forge` source code, from prerequisite setup through launching your first project.

## Prerequisites for SwarmForge Installation

Before installing SwarmForge, ensure your machine has all required dependencies. According to the [[`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md)](https://github.com/unclebob/swarm-forge/blob/main/README.md#L71-L78), you need:

| Tool | Purpose | Installation Notes |
|------|---------|------------------|
| `zsh` | Default shell for SwarmForge scripts | Usually pre-installed on macOS; `apt install zsh` on Ubuntu |
| `git` | Clone repository branches | `git --version` ≥ 2.x recommended |
| `tmux` | Terminal multiplexing for agent sessions | Core dependency for all SwarmForge operations |
| **Babashka** (`bb`) | Native Clojure scripting engine | Install via [babashka.org](https://babashka.org) |
| LLM backend | AI agent inference | One of: `codex`, `claude`, `copilot`, or `grok` |

Verify Babashka installation:

```bash
bb --version

```

## Install the get-swarm-forge Helper Script

The SwarmForge installation uses a helper script called `get-swarm-forge`. Place this script on your `PATH` so you can invoke it from any directory.

### Step 1: Copy the Helper to Your PATH

```bash
mkdir -p ~/cmds
cp get-swarm-forge ~/cmds/get-swarm-forge
chmod +x ~/cmds/get-swarm-forge

```

This excerpt follows the installation instructions in [[`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) lines 83-89](https://github.com/unclebob/swarm-forge/blob/main/README.md#L83-L89). The `~/cmds` directory is a common convention, but `~/bin` or any directory in your `$PATH` works equally well.

### Step 2: Initialize Your Forge Directory

Create a dedicated workspace—called the **forge**—that will hold all packs and projects:

```bash
mkdir -p ~/my-swarm-forge
cd ~/my-swarm-forge
get-swarm-forge

```

Running `get-swarm-forge` (source: [`get-swarm-forge` script](https://github.com/unclebob/swarm-forge/blob/main/get-swarm-forge)) performs the following automatically:

- Downloads the `main` branch and all pack branches (`two-pack`, `four-pack`, `six-pack`)
- Copies host scripts from `swarmforge/scripts/` into a local `swarmforge/` directory
- Places each pack's template under `packs/<pack-name>/`
- Creates an empty `projects/` folder for new projects

After this command completes, your directory structure resembles:

```

~/my-swarm-forge/
├── swarmforge/           # Host scripts and runtime

│   ├── scripts/
│   └── conf/
├── packs/
│   ├── two-pack/
│   ├── four-pack/
│   └── six-pack/
└── projects/             # Empty until you create projects

```

## Launch the SwarmForge Dashboard

Start the SwarmForge orchestration layer by running the wrapper script from your forge root:

```bash
./swarm

```

This command executes [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) to:

1. Boot the **lieutenant** agent (central coordinator)
2. Start the local web dashboard
3. Initialize the tmux session that hosts project agents

The dashboard prints a URL—also written to `.swarmforge/dashboard-url`—and automatically opens it in your default browser if the `open` command is available. See the launch instructions in [[`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) lines 101-107](https://github.com/unclebob/swarm-forge/blob/main/README.md#L101-L107).

## Create Your First Project

With the dashboard running, complete the SwarmForge setup by creating a project:

1. Click **New Project** in the web UI
2. Enter a project name (e.g., `demo`)
3. Select a pack: `two-pack`, `four-pack`, or `six-pack`
4. Optionally specify a GitHub repository
5. Confirm to create

The UI generates `projects/<name>/` containing:

- [`mission.md`](https://github.com/unclebob/swarm-forge/blob/main/mission.md) — project objectives and context
- Local [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) — pack-specific configuration
- Copy of the selected pack's directory structure

The chosen pack's agents start automatically in dedicated tmux windows.

## Optional Environment Configuration

Control SwarmForge behavior with environment variables before running `./swarm`:

| Variable | Default | Effect |
|----------|---------|--------|
| `SWARMFORGE_OPEN_BROWSER` | `1` | Set to `0` to suppress automatic browser launch |
| `SWARMFORGE_PREVENT_SLEEP` | `1` | Set to `0` to disable the OS sleep inhibitor |

Example with both disabled:

```bash
SWARMFORGE_OPEN_BROWSER=0 SWARMFORGE_PREVENT_SLEEP=0 ./swarm

```

## Complete Installation Command Reference

```bash

# 1. Install prerequisites (zsh, git, tmux, bb, and your LLM backend)

# 2. Install the get-swarm-forge helper

mkdir -p ~/cmds
cp get-swarm-forge ~/cmds/get-swarm-forge
chmod +x ~/cmds/get-swarm-forge

# 3. Create and initialize the forge

cd ~/my-swarm-forge
get-swarm-forge

# 4. Launch the dashboard

./swarm

# 5. Create a project via the web UI

#    → New Project → Name: hello-world → Pack: two-pack → Create

```

## Summary

- **Prerequisites**: `zsh`, `git`, `tmux`, Babashka (`bb`), and one LLM backend are mandatory for SwarmForge operation
- **Helper script**: `get-swarm-forge` downloads all branches and establishes the `packs/` and `projects/` directory structure
- **Launcher**: `./swarm` starts the lieutenant, dashboard, and tmux session from your forge root
- **Project creation**: Use the web dashboard to instantiate projects; each project receives its own [`mission.md`](https://github.com/unclebob/swarm-forge/blob/main/mission.md) and agent configuration
- **No external dependencies**: After the initial `get-swarm-forge` run, SwarmForge operates entirely offline

## Frequently Asked Questions

### What operating systems support SwarmForge?

SwarmForge runs on any Unix-like system with `zsh`, `git`, `tmux`, and Babashka. macOS and Linux distributions are fully supported. Windows users can run SwarmForge via WSL2 with these tools installed.

### Can I install SwarmForge without Babashka?

No. Babashka (`bb`) is a hard dependency. The `get-swarm-forge` script and all runtime orchestration in [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) rely on Clojure scripting that Babashka provides natively without a JVM.

### Where are my projects stored after installation?

Projects live in the `projects/` subdirectory of your forge root—created when you first run `get-swarm-forge`. Each project receives its own folder with [`mission.md`](https://github.com/unclebob/swarm-forge/blob/main/mission.md), local configuration, and working files. The dashboard creates these directories automatically.

### How do I switch between different pack configurations?

During project creation, select `two-pack`, `four-pack`, or `six-pack` from the dashboard dropdown. Each pack defines a different agent topology in [`swarmforge/conf/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/conf/swarmforge.conf), determining how many specialized agents collaborate on tasks.