How SwarmForge Prevents System Sleep During an Active Swarm

SwarmForge prevents system sleep by launching an OS-specific sleep inhibitor—caffeinate on macOS or systemd-inhibit on Linux—at swarm startup and terminating it during cleanup.

When running long-lived AI agent swarms, unexpected system sleep can interrupt critical tasks. The unclebob/swarm-forge repository implements a robust sleep prevention mechanism that automatically detects the host operating system and spawns the appropriate inhibitor process for the entire duration of the swarm session.

OS-Specific Sleep Inhibitor Implementation

SwarmForge determines which sleep prevention tool to use through platform detection logic located in swarmforge/scripts/swarmforge.bb. The system checks for executable availability and operating system type before constructing the inhibition command.

The sleep-inhibitor-prefix Function

At lines 374–383 of swarmforge/scripts/swarmforge.bb, the sleep-inhibitor-prefix function builds a command vector based on the detected platform:

(defn sleep-inhibitor-prefix []
  (cond
    (and (util/os-mac?) (executable? "caffeinate"))
      ["caffeinate" "--why=sleep:active"]
    (and (util/os-linux?) (executable? "systemd-inhibit"))
      ["systemd-inhibit" "--what=idle"]
    :else []))

This function returns ["caffeinate" "--why=sleep:active"] for macOS systems where caffeinate is available, or ["systemd-inhibit" "--what=idle"] for Linux systems with systemd-inhibit. If neither tool is present, it returns an empty vector, allowing the swarm to run without sleep prevention.

Launching the Inhibitor at Startup

The inhibitor process starts during step 9 of the startup sequence, as documented in README.md (lines 69–70). After parsing the configuration in swarmforge/swarmforge.conf, the launcher executes the constructed inhibitor command in the background before initializing tmux sessions:

(let [command (into (vec (sleep-inhibitor-prefix))
                    (when (> (count command) 2)
                      " with OS sleep prevention"))]
  (when (seq command)
    (sh (first command) (rest command) :bg true)))

This background process remains active for the entire swarm lifecycle, keeping the host machine awake while agents execute their tasks.

Configuring Sleep Prevention Behavior

Disabling Sleep Inhibition

Users can opt out of sleep prevention by setting the SWARMFORGE_PREVENT_SLEEP environment variable to 0 before invoking the swarm command. This behavior is documented in README.md (lines 87–88):

# Run swarm with sleep prevention disabled

SWARMFORGE_PREVENT_SLEEP=0 ./swarm up

# Default behavior with sleep prevention enabled

SWARMFORGE_PREVENT_SLEEP=1 ./swarm up

When SWARMFORGE_PREVENT_SLEEP is set to 0, the sleep-inhibitor-prefix function returns an empty vector regardless of the operating system, causing the launcher to skip the inhibitor creation entirely.

Cleanup and Process Management

When the swarm terminates, the cleanup routine in swarmforge/scripts/swarmforge.bb kills the background inhibitor process. This ensures that caffeinate or systemd-inhibit does not continue running after the swarm session ends, preventing orphaned processes from consuming system resources or blocking normal sleep behavior indefinitely.

Summary

• Automatic OS detection: The sleep-inhibitor-prefix function in swarmforge/scripts/swarmforge.bb (lines 374–383) selects caffeinate for macOS or systemd-inhibit for Linux based on platform checks.
• Startup integration: The inhibitor launches during step 9 of the startup sequence, running as a background process for the swarm's duration.
• User control: Set SWARMFORGE_PREVENT_SLEEP=0 to disable the feature, as documented in README.md (lines 87–88).
• Proper cleanup: The swarm cleanup routine terminates the inhibitor process when the session ends, ensuring no stray processes remain.

Frequently Asked Questions

What sleep prevention tools does SwarmForge use?

According to the source code in swarmforge/scripts/swarmforge.bb, SwarmForge uses caffeinate on macOS (with the --why=sleep:active flag) and systemd-inhibit on Linux (with the --what=idle flag). If neither tool is available on the system, the swarm runs without sleep prevention.

How do I disable sleep prevention in SwarmForge?

Set the environment variable SWARMFORGE_PREVENT_SLEEP to 0 before running the swarm command: SWARMFORGE_PREVENT_SLEEP=0 ./swarm up. This overrides the default behavior and prevents the launcher from starting any sleep inhibitor process.

Where is the sleep inhibitor configured in the source code?

The sleep inhibition logic resides in swarmforge/scripts/swarmforge.bb at lines 374–383 within the sleep-inhibitor-prefix function. The feature is documented in README.md at lines 87–88, and the startup integration occurs at step 9 of the initialization sequence (lines 69–70).

Does sleep prevention work on all operating systems?

Sleep prevention works on macOS systems with caffeinate installed and Linux systems with systemd-inhibit available. On other platforms or systems lacking these utilities, SwarmForge gracefully degrades by running the swarm without sleep inhibition, as the sleep-inhibitor-prefix function returns an empty vector when no suitable tool is detected.

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