Configuring Sleep Prevention Behavior Across macOS and Linux in SwarmForge

SwarmForge automatically prevents your host computer from sleeping while a swarm is active by launching an OS-specific sleep inhibitor before the hand-off daemon starts.

SwarmForge's sleep prevention system is implemented in Babashka and adapts to your operating system without manual configuration. Whether you're running long-running distributed tasks on a MacBook or a Linux workstation, the tool detects your platform and applies the appropriate inhibitor command. This guide explains how the feature works, how to disable it, and where to customize it in the unclebob/swarm-forge codebase.

---

How Sleep Prevention Works in SwarmForge

SwarmForge defers sleep inhibition until the hand-off daemon launches. The core logic resides in swarmforge/scripts/swarmforge.bb, where two key functions collaborate to build and execute the inhibitor command.

The sleep-inhibitor-prefix Function

This function constructs the appropriate command vector based on your OS and available system utilities:

(defn sleep-inhibitor-prefix []
  (when-not (= "0" (System/getenv "SWARMFORGE_PREVENT_SLEEP"))
    (case (uname)
      "Darwin" (when (command-exists? "caffeinate")
                 ["caffeinate" "-dims"])
      "Linux"  (when (and (command-exists? "systemd-inhibit")
                          (command-exists? "systemctl")
                          (system-running?))
                 ["systemd-inhibit"
                  "--what=sleep:idle"
                  "--who=SwarmForge"
                  "--why=\"SwarmForge swarm is active\""])
      nil)))

The function returns nil when SWARMFORGE_PREVENT_SLEEP is set to "0" or when no suitable inhibitor is found.

The start-handoff-daemon! Function

This function prepends the inhibitor vector to the daemon launch command at lines 99-107 of swarmforge.bb. When an inhibitor is present, the daemon process runs as a child of that inhibitor, ensuring the system stays awake for the duration of the swarm.

---

Platform-Specific Sleep Inhibitors

SwarmForge uses different inhibition strategies depending on your operating system.

macOS: caffeinate -dims

• Command: caffeinate -dims
• Activation: Only when the caffeinate binary exists in $PATH
• Behavior: Creates an assertion that prevents idle sleep, display sleep, and system sleep (-i = idle, -d = display, -m = system, -s = prevent idle sleep)

The -dims flags ensure your MacBook stays awake even if you close the lid (when connected to power) or step away from the keyboard.

Linux: systemd-inhibit

• Command: systemd-inhibit --what=sleep:idle --who=SwarmForge --why="..."
• Activation: Requires all three conditions:
  • systemd-inhibit binary exists
  • systemctl binary exists
  • systemctl is-system-running returns running or degraded

SwarmForge checks systemd's operational state to avoid launching inhibitors on non-systemd systems or during system startup/shutdown transitions.

---

Disabling Sleep Prevention

You can disable sleep prevention entirely by setting an environment variable before launch.

Disable via Environment Variable

# Allow the system to sleep normally while SwarmForge runs

SWARMFORGE_PREVENT_SLEEP=0 ./swarm

This causes sleep-inhibitor-prefix to return nil at line 85-86, and the daemon starts without any inhibitor wrapper.

Persistent Disable in Shell Profile

# Add to ~/.bashrc, ~/.zshrc, or equivalent

export SWARMFORGE_PREVENT_SLEEP=0

The README documents this option at lines 29-30.

---

Customizing the Inhibitor Behavior

For advanced use cases, you can override the inhibitor selection by modifying swarmforge.bb.

Force caffeinate on Linux

If you prefer caffeinate (available via Homebrew Linux) over systemd-inhibit:

;; Modified swarmforge.bb
(defn sleep-inhibitor-prefix []
  (when-not (= "0" (System/getenv "SWARMFORGE_PREVENT_SLEEP"))
    (case (uname)
      "Darwin" (when (command-exists? "caffeinate")
                 ["caffeinate" "-dims"])
      "Linux"  (when (command-exists? "caffeinate")
                 ["caffeinate" "-dims"])  ; Override: use caffeinate on Linux
      nil)))

Add a Custom Inhibitor for Other Platforms

To support FreeBSD or other Unix variants:

(defn sleep-inhibitor-prefix []
  (when-not (= "0" (System/getenv "SWARMFORGE_PREVENT_SLEEP"))
    (case (uname)
      "Darwin" (when (command-exists? "caffeinate")
                 ["caffeinate" "-dims"])
      "Linux"  (when (and (command-exists? "systemd-inhibit")
                          (command-exists? "systemctl")
                          (system-running?))
                 ["systemd-inhibit" "--what=sleep:idle" "--who=SwarmForge"
                  "--why=\"SwarmForge swarm is active\""])
      "FreeBSD" (when (command-exists? "zzz")
                  ["doas" "zzz" "-S" "disabled"])
      nil)))

---

Key Source Files

File	Purpose	Location
swarmforge/scripts/swarmforge.bb	Core sleep inhibitor logic: sleep-inhibitor-prefix, start-handoff-daemon!	Lines 85-107
README.md	User documentation for SWARMFORGE_PREVENT_SLEEP	Lines 29-30
swarmforge/scripts/stop_handoff_daemon.bb	Daemon termination (indirectly stops inhibitor via process tree)	Full file

---

Summary

• Automatic detection: SwarmForge chooses caffeinate on macOS and systemd-inhibit on Linux without configuration.
• Disable anytime: Set SWARMFORGE_PREVENT_SLEEP=0 to allow normal system sleep behavior.
• Linux requirements: systemd-inhibit requires a running systemd state (running or degraded).
• Extensible design: The sleep-inhibitor-prefix function in swarmforge.bb enables fork-level customization for unsupported platforms or preferences.

---

Frequently Asked Questions

Why does SwarmForge prevent sleep by default?

Long-running swarm tasks can fail or lose state if the host sleeps during execution. The default inhibition ensures reliability for distributed workloads without requiring user awareness of sleep settings.

What happens if no inhibitor is available on Linux?

If systemd-inhibit is missing or systemd is not running, sleep-inhibitor-prefix returns nil and the daemon launches without inhibition. The swarm operates normally but the system may sleep according to its power settings.

Can I use a different inhibitor without modifying the source?

Not directly. You must either fork and modify swarmforge.bb, or wrap the entire ./swarm invocation with your preferred inhibitor command using a shell alias or wrapper script.

Does sleep prevention affect battery life on laptops?

Yes. Sleep inhibition keeps CPUs, disks, and network interfaces active. For battery-powered operation, consider setting SWARMFORGE_PREVENT_SLEEP=0 and configuring longer swarm check pointing intervals instead.

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