# How to Configure SwarmForge: A Step-by-Step Guide to Role Hierarchies and Trust Settings

> Configure SwarmForge with this step-by-step guide. Learn to set up role hierarchies and trust settings by editing configuration files for seamless agent operation.

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

---

**Configure SwarmForge by editing two text-based files: [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) defines which agents run and in what order, while `~/.config/swarmforge/config.toml` stores trust permissions so agents launch without repeated prompts.**

SwarmForge orchestrates AI-driven software engineering pipelines through a lightweight configuration system. This guide walks through the two essential files that control agent roles and host permissions, with direct references to the source implementation in the `unclebob/swarm-forge` repository.

---

## The Two Core Configuration Files

SwarmForge configuration splits cleanly between **pack-level role definitions** and **host-level trust settings**.

| File | Purpose | Location | Format |
|------|---------|----------|--------|
| [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) | Role hierarchy and startup order | `<repo-root>/swarmforge/swarmforge.conf` | Plain text, one role per line |
| [`config.toml`](https://github.com/unclebob/swarm-forge/blob/main/config.toml) | Trust levels for pack directories | `~/.config/swarmforge/config.toml` or `$HOME/config.toml` | TOML with `[[projects]]` arrays |

---

## Configuring the Role Hierarchy in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)

The [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) file tells SwarmForge which agents to instantiate, which backend each uses, and what command-line flags to pass.

### File Format

Each non-comment line follows this pattern:

```text
RoleName backend-name [--optional-flags]

```

Comment lines beginning with `#` are ignored by the parser in `swarmforge/scripts/swarmforge.bb` (see the `parse-config` function).

### Example Configuration

```text

# Host lieutenant. Default is grok with no extra args.

Lieutenant grok --yolo
Coder codex
Cleaner gpt-4
Architect claude
QA gpt-4

```

### How the Launcher Parses This File

When you run `./swarm`, the entry-point script `swarmforge/scripts/swarmforge.bb` executes:

1. Calls `parse-config` to read [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf)
2. Extracts the Lieutenant configuration separately via `parse-lieutenant-config`
3. Spawns a dedicated **tmux window** for each role, isolating its git worktree
4. Maintains the order defined in the configuration file

The test suite in `test/swarmforge/pack_ui_test.clj` validates that this role order is respected by the UI.

### Creating Your Own [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)

```bash
cat > swarmforge/swarmforge.conf <<'EOF'

# Define the role chain for this pack

Lieutenant grok --yolo
Coder codex
Cleaner gpt-4
Architect claude
QA gpt-4
EOF

```

---

## Setting Up Trust Permissions in [`config.toml`](https://github.com/unclebob/swarm-forge/blob/main/config.toml)

Without trust configuration, SwarmForge prompts you to approve every agent launch. The [`config.toml`](https://github.com/unclebob/swarm-forge/blob/main/config.toml) eliminates this friction by pre-authorizing specific pack directories.

### Manual Trust Configuration

```bash
CONFIG="$HOME/.config/swarmforge/config.toml"
mkdir -p "$(dirname "$CONFIG")"
cat >> "$CONFIG" <<EOF

[[projects]]
path = "$(pwd)/packs/six-pack"
trust_level = "trusted"
EOF

```

### Trust Verification Logic

The launcher checks trust status before spawning agents. The test `trust-does-not-duplicate-existing-config` in the codebase confirms that duplicate entries are handled gracefully—SwarmForge appends new trust records only when the path isn't already present.

### Critical Requirement

The `path` value must be an **absolute path**. Relative paths will fail the trust check, forcing interactive prompts.

---

## Complete Configuration Workflow

Follow this sequence to fully configure SwarmForge:

1. **Initialize the pack**

   ```bash
   get-swarm-forge six-pack   # or two-pack / four-pack

   cd six-pack
   ```

2. **Define roles** — Edit [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) with your agent chain

3. **Establish trust** — Create `~/.config/swarmforge/config.toml` with the absolute pack path

4. **Launch**

   ```bash
   ./swarm
   ```

This creates a tmux session with one window per configured role. Agents begin processing cards according to the shared constitution articles (`engineering.prompt`, `workflow.prompt`, etc.).

---

## Verification: Confirming Correct Role Order

The following Playwright test snippet validates that the dashboard reflects your [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) configuration:

```js
const { expect } = require('@playwright/test');

test('roles start in config order', async ({ page }) => {
  await page.goto('http://localhost:3000/dashboard');
  const roleHeaders = await page.$$eval('.role-header', 
    els => els.map(e => e.textContent));
  expect(roleHeaders).toEqual([
    'Lieutenant', 'Coder', 'Cleaner', 'Architect', 'QA'
  ]);
});

```

---

## Handoff Protocol: Beyond Configuration

Agent communication operates independently of configuration files. The **handoff protocol**—described in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) and validated by `test/swarmforge/handoff_test.clj`—uses three shell scripts to coordinate work:

- [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) — Initiates work transfer
- [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) — Signals completion readiness
- [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) — Confirms task finalization

No additional configuration is required to enable this protocol.

---

## Summary

- **[`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)** defines the **role hierarchy**, **backend selection**, and **startup order** for each pack
- **[`config.toml`](https://github.com/unclebob/swarm-forge/blob/main/config.toml)** stores **trust permissions** to enable automatic agent launches without prompts
- The **launcher script** `swarmforge/scripts/swarmforge.bb` parses both files via `parse-config` and `parse-lieutenant-config`
- **Absolute paths** are mandatory in trust entries
- **Tmux windows** isolate each role's git worktree according to the configuration

---

## Frequently Asked Questions

### What happens if I don't create a [`config.toml`](https://github.com/unclebob/swarm-forge/blob/main/config.toml) file?

SwarmForge will prompt you to approve each agent launch interactively. The system functions without trust configuration, but requires manual confirmation for every role instantiation.

### Can I use relative paths in the [`config.toml`](https://github.com/unclebob/swarm-forge/blob/main/config.toml) trust entry?

No. The trust check requires absolute paths. Relative paths will fail validation, causing SwarmForge to treat the pack as untrusted and prompt for approval.

### How do I change which AI backend a role uses?

Edit the backend name in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf). For example, change `Coder codex` to `Coder claude` or `Coder gpt-4`. Any backend identifier supported by your SwarmForge installation can be specified.

### Where can I find the sample configuration files?

The repository includes a minimal [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) at [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) (currently four empty comment lines). The [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) provides installation instructions and links to helper scripts for pack initialization.