# How to Configure Agent Backends per Role in swarmforge.conf

> Configure agent backends per role in swarmforge.conf. Map roles to specific backend commands using the format <RoleName> <backend> [flags] for customized swarm-forge deployments.

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

---

**Edit [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) to map each role to a specific backend command, using the format `<RoleName> <backend> [flags]`.**

The [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) file in Swarm-Forge controls which **agent backend** executes for each defined role. This configuration file lives at [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) and uses a simple line-based syntax that pairs role names with their corresponding backend executables and optional arguments.

## Understanding the swarmforge.conf Format

Each non-comment line in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) follows this structure:

```

<Role-Name> <backend-command> [extra-flags...]

```

- **Role-Name**: The exact role identifier defined in the Swarm-Forge constitution (e.g., `Lieutenant`, `Sergeant`, `Engineer`). This must match the role name used in prompt files like `swarmforge/roles/lieutenant.prompt`.
- **backend-command**: The executable that implements the agent (e.g., `grok`, `claude`, `openai`, or a custom script path).
- **extra-flags**: Optional arguments passed verbatim to the backend (e.g., `--yolo`, `--model gpt-4`, `--temperature 0.7`).

Lines beginning with `#` are treated as comments and ignored during parsing.

## Step-by-Step Configuration

Follow these steps to configure backends for specific roles:

1. **Locate the configuration file** at [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf).

2. **Add or modify entries** for each role requiring a custom backend.

3. **Save the file**—Swarm-Forge reads [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) at startup and builds a lookup table mapping roles to their backend commands.

4. **Verify role names match** the definitions in `swarmforge/roles/` directory files (e.g., `lieutenant.prompt`, `sergeant.prompt`).

## Practical Configuration Examples

Here are common patterns for configuring agent backends per role:

```conf

# Lieutenant uses Grok with yolo mode enabled

Lieutenant grok --yolo

# Sergeant runs Claude without additional flags

Sergeant claude

# Engineer targets OpenAI's GPT-4 with custom temperature

Engineer openai --model gpt-4 --temperature 0.7

# Analyst uses a project-specific custom agent script

Analyst ./bin/custom-agent.sh --verbose

```

Multiple roles can share the same backend with different flag configurations, or each role can use entirely distinct backend implementations.

## Backend Launch Mechanism

The core launch logic resides in `swarmforge/scripts/swarm_tool.bb`. This script:

- Parses [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) line-by-line during initialization
- Builds an in-memory mapping of role names to backend commands
- Spawns the appropriate backend process when a role is activated
- Falls back to default behavior (`grok` with no arguments) if a role lacks explicit configuration

## Key Files Reference

| File | Purpose |
|------|---------|
| [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) | Primary configuration file for role-to-backend mapping |
| `swarmforge/scripts/swarm_tool.bb` | Core script that reads configuration and launches backend processes |
| `swarmforge/roles/lieutenant.prompt` | Role prompt definition—the name must match the config entry |
| `swarmforge/roles/sergeant.prompt` | Role prompt definition for Sergeant |
| `swarmforge/roles/engineer.prompt` | Role prompt definition for Engineer |

## Summary

- **[`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)** uses simple `<Role> <backend> [flags]` syntax to configure agent backends per role
- **Role names** must exactly match definitions in the `swarmforge/roles/` directory
- **Backend commands** can be standard executables (`grok`, `claude`, `openai`) or custom scripts
- **`swarm_tool.bb`** handles configuration parsing and backend process spawning
- Changes take effect on the next Swarm-Forge startup with no additional build step required

## Frequently Asked Questions

### What happens if a role is not defined in swarmforge.conf?

Swarm-Forge falls back to the default backend behavior. According to the implementation in `swarm_tool.bb`, unconfigured roles default to `grok` executed with no command-line arguments.

### Can I use absolute paths for custom backend scripts?

Yes—any valid executable path works as the backend command. Relative paths resolve from the Swarm-Forge working directory. For predictable behavior, use absolute paths or paths relative to the project root (e.g., [`./bin/custom-agent.sh`](https://github.com/unclebob/swarm-forge/blob/main/./bin/custom-agent.sh)).

### How do I verify my configuration is being read correctly?

Check the startup output from `swarm_tool.bb`. The script reports which backend it launches for each activated role. If a role launches the wrong backend, confirm the role name spelling matches exactly between [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) and the corresponding file in `swarmforge/roles/`.