# SwarmForge Environment Variables: Complete Startup Configuration Guide > Configure SwarmForge startup with essential environment variables. Learn how to control agent delays, sleep prevention, and more for optimal performance. - Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge) - Tags: how-to-guide - Published: 2026-08-08 --- **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`](https://github.com/unclebob/swarm-forge/blob/main/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 ```bash # 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.