How to Configure Agent Backends per Role in swarmforge.conf

Edit swarmforge.conf to map each role to a specific backend command, using the format <RoleName> <backend> [flags].

The swarmforge.conf file in Swarm-Forge controls which agent backend executes for each defined role. This configuration file lives at 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 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.

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

3. Save the file—Swarm-Forge reads 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:

# 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 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	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 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).

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 and the corresponding file in swarmforge/roles/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}