SwarmForge Environment Variables: Complete Startup Configuration Guide

SwarmForge reads five critical environment variables during initialization to control agent delays, sleep prevention, terminal backends, and hand-off roles.

SwarmForge startup behavior is governed by environment variables parsed in the main Babashka entry point. Understanding these swarmforge.bb configuration options allows you to tune agent orchestration timing, terminal integration, and cross-node hand-off protocols before the first process spawns.

Core SwarmForge Environment Variables

The unclebob/swarm-forge repository reads specific environment variables during the initialization phase of swarmforge/scripts/swarmforge.bb. These settings are evaluated once at startup and cannot be changed without restarting the process.

SWARMFORGE_AGENT_START_DELAY_MS

In swarmforge.bb at line 535, the env-long function reads this variable to introduce a blocking delay before the first agent process spawns. The default value is 1500 ms, which provides time for dependent services to become ready.

Setting this variable is essential when your swarm depends on external resources that need initialization time.

SWARMFORGE_PREVENT_SLEEP

Checked early in swarmforge.bb at line 375, this boolean flag controls host sleep prevention. When set to a non-zero value, SwarmForge starts a background caffeinate or systemd-inhibit process to keep the host awake while the swarm is active.

Setting this variable to 0 explicitly disables the sleep-prevention behavior, allowing laptops to enter sleep mode during swarm operations.

SWARMFORGE_TERMINAL

Read at the very beginning of swarmforge.bb (line 53) and also in the helper script close-swarm (line 71), this variable overrides the automatic terminal-backend detection. When SWARMFORGE_TERMINAL_BACKEND is not set, the value of SWARMFORGE_TERMINAL is copied to that variable to determine the terminal implementation.

SWARMFORGE_TERMINAL_BACKEND

Consumed throughout the codebase—including in test/swarmforge/script_test.clj (line 296) and swarmforge/scripts/swarm-cleanup.sh (line 11)—this variable directly selects the terminal-backend implementation. Valid values include terminal-app, ghostty, windows-terminal, and none.

Explicitly setting this variable bypasses the automatic detection logic and the fallback copy operation from SWARMFORGE_TERMINAL.

SWARMFORGE_ROLE

Evaluated in swarmforge/scripts/swarm_handoff.bb at line 74, this variable determines the node's role in the distributed hand-off protocol. The value must be set to either sender or receiver before invoking any hand-off command.

This variable is critical for multi-node swarms where agents migrate between hosts.

Configuration Timing and Scope

These environment variables are read once when the swarm command or any helper script starts. Changing values after the process has initialized has no effect; you must export variables in the shell environment before invoking the command.

Practical Configuration Examples

# 1️⃣ Disable host‑sleep prevention (useful on laptops you want to let sleep)

export SWARMFORGE_PREVENT_SLEEP=0
./swarm   # Swarm will start without launching caffeinate/systemd‑inhibit

# 2️⃣ Add a 3‑second delay before the first agent is spawned

export SWARMFORGE_AGENT_START_DELAY_MS=3000
./swarm

# 3️⃣ Force the use of the “ghostty” terminal backend, regardless of auto‑detect

export SWARMFORGE_TERMINAL=ghostty
./swarm

# 4️⃣ Explicitly set the terminal backend (bypasses the SWARMFORGE_TERMINAL copy‑over)

export SWARMFORGE_TERMINAL_BACKEND=ghostty
./swarm

# 5️⃣ Choose the hand‑off role for a node

export SWARMFORGE_ROLE=sender   # or “receiver”

./swarm_handoff   # will run as the chosen role

Summary

• SWARMFORGE_AGENT_START_DELAY_MS controls the initial delay before agent creation via env-long in swarmforge.bb (default 1500 ms)
• SWARMFORGE_PREVENT_SLEEP enables or disables sleep-prevention daemons at line 375 of the main script
• SWARMFORGE_TERMINAL and SWARMFORGE_TERMINAL_BACKEND configure terminal integration across swarmforge.bb, close-swarm, and cleanup scripts
• SWARMFORGE_ROLE establishes the node as either sender or receiver in the hand-off protocol defined in swarm_handoff.bb
• All variables are evaluated at process startup and require export before command execution

Frequently Asked Questions

What is the default agent start delay in SwarmForge?

The default delay is 1500 milliseconds, as defined by the env-long function in swarmforge/scripts/swarmforge.bb at line 535. This pause ensures dependent services are ready before the first agent process spawns.

How do I disable sleep prevention in SwarmForge?

Set SWARMFORGE_PREVENT_SLEEP=0 in your environment before running the swarm command. According to the source at line 375 of swarmforge.bb, a zero value prevents the launch of caffeinate or systemd-inhibit background processes.

What is the difference between SWARMFORGE_TERMINAL and SWARMFORGE_TERMINAL_BACKEND?

SWARMFORGE_TERMINAL is read at line 53 of swarmforge.bb and line 71 of close-swarm as a user-facing override, while SWARMFORGE_TERMINAL_BACKEND is the internal variable consumed by the test suite and cleanup scripts. If the backend variable is unset, the system copies the terminal variable's value to it.

When should I set SWARMFORGE_ROLE?

You must set SWARMFORGE_ROLE to either sender or receiver before invoking ./swarm_handoff, as validated at line 74 of swarmforge/scripts/swarm_handoff.bb. This variable is only relevant when performing distributed hand-off operations between nodes.

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