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

> Install SwarmForge with our complete setup guide. Learn to install prerequisites, copy the helper script, and launch your AI agent orchestration dashboard quickly and easily.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-09-02

---

**SwarmForge installation requires installing prerequisites (zsh, git, tmux, Babashka, and an LLM backend), copying the `get-swarm-forge` helper to your PATH, running it once in your chosen forge directory, and launching the dashboard with `./swarm`.**

SwarmForge is a tmux‑based orchestration platform for running AI‑agent swarms, developed by Uncle Bob (Robert C. Martin) in the `unclebob/swarm-forge` repository. This guide walks through the complete installation process using the actual source files and scripts from the project.

## Prerequisites for Running SwarmForge

Before installing SwarmForge, ensure your machine has the following tools available:

- **zsh** — the Z shell environment
- **git** — for cloning branches and managing packs
- **tmux** — terminal multiplexer for session management
- **Babashka (`bb`)** — native Clojure scripting engine that powers the runtime
- **At least one LLM backend** — `codex`, `claude`, `copilot`, or `grok`

These requirements are documented in [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) at lines 71–78 of the source repository.

## Install the `get-swarm-forge` Helper Script

The `get-swarm-forge` script is the bootstrap installer for the entire platform. It handles downloading all branches, setting up the directory structure, and preparing the forge workspace.

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

Choose a directory on your shell PATH (commonly `~/cmds` or `~/bin`):

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

```

This snippet comes directly from the installation section in [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) (lines 83–89).

### Step 2: Run the Installer in Your Forge Directory

Navigate to any empty directory you want to become your **forge** — the root workspace that will hold all packs and projects:

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

```

Running `get-swarm-forge` once performs the following actions (as implemented in the `get-swarm-forge` script):

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

No further network access is required after this initial run.

## Start the SwarmForge Dashboard

From the forge root directory, launch the orchestration system:

```bash
./swarm

```

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

- Start the **lieutenant** agent
- Launch the local web dashboard
- Initialize the tmux session for hosting project agents

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

## Create Your First Project

Once the dashboard is running:

1. Click **New Project**
2. Enter a project name
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:
- A [`mission.md`](https://github.com/unclebob/swarm-forge/blob/main/mission.md) file for project context
- A copy of the selected pack's configuration
- Automatically started agents for the chosen pack topology

## Optional Environment Configuration

Control SwarmForge behavior with these environment variables:

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

Example:

```bash
SWARMFORGE_OPEN_BROWSER=0 ./swarm

```

## Complete Installation Example

```bash

# Install the helper script

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

# Create and populate your forge

mkdir -p ~/swarm-forge
cd ~/swarm-forge
get-swarm-forge

# Launch the platform

./swarm

# → Dashboard URL printed and opened in browser

# (In browser) Create project "demo" with two-pack topology

# → New Project → Name: demo → Pack: two-pack → Create

```

## Key Files in the SwarmForge Installation

Understanding these files helps troubleshoot and extend your installation:

| File | Location | Purpose |
|------|----------|---------|
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) | Repository root | Official documentation and prerequisites |
| `get-swarm-forge` | Repository root | Bootstrap installer that downloads branches and creates the forge structure |
| `swarm` | Forge root after install | Launcher wrapper that starts the dashboard |
| [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) | `swarmforge/scripts/` | Core runtime that boots tmux sessions and orchestrates agents |
| [`swarmforge/conf/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/conf/swarmforge.conf) | Inside each pack | Defines window/role topology for that pack |
| `swarmforge/constitution/articles/*.prompt` | `swarmforge/constitution/` | Shared engineering rules inherited by all packs |
| `packs/<pack>/swarmforge/roles/*.prompt` | Per-pack | Role‑specific prompts for each LLM backend |
| `projects/<name>/` | Generated at runtime | Project workspace with [`mission.md`](https://github.com/unclebob/swarm-forge/blob/main/mission.md) and local configuration |

## Summary

SwarmForge installation follows a clear three‑phase pattern:

- **Prepare prerequisites**: zsh, git, tmux, Babashka, and an LLM backend
- **Bootstrap with `get-swarm-forge`**: Copy the helper to PATH, run once in your chosen directory to download all branches and create the forge structure
- **Launch with `./swarm`**: Start the dashboard, create projects through the web UI, and begin orchestrating agent swarms

The entire process is self‑contained after the initial download, with all runtime logic living in [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) and configuration managed through pack templates and project workspaces.

## Frequently Asked Questions

### What is the minimum system requirement for SwarmForge?

You need a Unix‑like system with **zsh**, **git**, **tmux**, and **Babashka** installed, plus at least one supported LLM backend (`codex`, `claude`, `copilot`, or `grok`). No Docker or container runtime is required. The platform runs entirely through shell scripts and tmux sessions.

### Can I install SwarmForge without cloning the entire repository first?

Yes. Copy only the `get-swarm-forge` script from the `unclebob/swarm-forge` repository, place it on your PATH, and run it. This script downloads the `main` branch and all pack branches automatically. You do not need a prior `git clone` of the repository.

### Where does SwarmForge store project data?

All project data lives in the `projects/` directory under your forge root, created by `get-swarm-forge` during installation. Each project gets its own subdirectory containing [`mission.md`](https://github.com/unclebob/swarm-forge/blob/main/mission.md), a local [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf), and generated worktrees. The dashboard URL is cached in `.swarmforge/dashboard-url` at the forge root.

### How do I switch between different agent pack sizes?

During project creation in the dashboard, select from `two-pack`, `four-pack`, or `six-pack`. Each pack template resides in `packs/<pack-name>/` with its own [`swarmforge/conf/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/conf/swarmforge.conf) defining the window and role topology. You cannot change a project's pack after creation; create a new project with the desired pack instead.