SwarmForge Sleep Inhibitor: How It Works on macOS vs Linux and How to Disable It

The SwarmForge sleep inhibitor prevents your host from sleeping while a swarm is active by prepending an OS-specific command—caffeinate on macOS or systemd-inhibit on Linux—to the handoff daemon launch command, and you can disable it by setting SWARMFORGE_PREVENT_SLEEP=0.

SwarmForge's sleep inhibitor ensures long-running swarms aren't interrupted by the operating system's power management. According to the unclebob/swarm-forge source code, this feature automatically detects your platform and applies the appropriate system-level sleep prevention mechanism. Understanding how this works helps you troubleshoot power-related issues or intentionally allow sleep during swarm execution.

How the Sleep Inhibitor Works

The core logic resides in swarmforge/scripts/swarmforge.bb within the function sleep-inhibitor-prefix. This Clojure function inspects the environment and operating system, then returns either a command vector to prepend or nil to skip inhibition.

(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")
                         (linux-systemd-running?))
                ["systemd-inhibit"
                 "--what=sleep:idle"
                 "--who=SwarmForge"
                 "--why=SwarmForge swarm is active"])
      nil)))

The function follows a clear decision path:

• First, it checks the SWARMFORGE_PREVENT_SLEEP environment variable. If set to "0", it immediately returns nil and no inhibitor is applied.
• Next, it branches based on uname output for platform-specific behavior.

macOS Sleep Inhibition with caffeinate

On macOS (Darwin), SwarmForge uses Apple's native caffeinate utility. When the binary exists in PATH, the function returns ["caffeinate" "-dims"].

The -dims flags specify:

• -d — Prevent display sleep
• -i — Prevent idle sleep
• -m — Prevent disk idle sleep
• -s — Prevent system sleep

These flags ensure the handoff daemon keeps the machine fully awake until it terminates. The caffeinate command is prepended directly to the daemon launch, so inheritance is automatic—no additional process management required.

Linux Sleep Inhibition with systemd-inhibit

On Linux, SwarmForge leverages systemd's inhibition mechanism. The function verifies three conditions before applying the inhibitor:

1. systemd-inhibit binary exists
2. systemctl binary exists
3. systemd reports a running or degraded state (via linux-systemd-running?)

When all conditions pass, the returned command vector is:

systemd-inhibit \
  --what=sleep:idle \
  --who=SwarmForge \
  --why="SwarmForge swarm is active"

This creates a transient systemd inhibitor lock that blocks both suspend and idle sleep while the handoff daemon remains alive. The lock automatically releases when the daemon process exits, even on crash or abnormal termination.

How to Disable the Sleep Inhibitor

To completely disable SwarmForge's sleep prevention, export SWARMFORGE_PREVENT_SLEEP=0 before executing ./swarm. This bypasses all OS-specific inhibitor logic and allows normal system sleep behavior.

Disabling via Environment Variable

# Disable sleep inhibitor for a single run

SWARMFORGE_PREVENT_SLEEP=0 ./swarm

# Or export for the current shell session

export SWARMFORGE_PREVENT_SLEEP=0
./swarm

When disabled, sleep-inhibitor-prefix returns nil, and start-handoff-daemon! launches the handoff daemon without any prefix commands. The OS power management policies apply normally.

Runtime Inspection and Verification

You can verify which inhibitor (if any) would apply on your system using the Clojure REPL:

(require '[swarmforge.scripts.swarmforge :as sf])

;; Check the computed prefix for current platform
(sf/sleep-inhibitor-prefix)

;; Expected outputs:
;; => ["caffeinate" "-dims"]                    ; macOS with caffeinate available
;; => ["systemd-inhibit" "--what=sleep:idle" "--who=SwarmForge" "--why=SwarmForge swarm is active"]
;; => nil                                        ; when SWARMFORGE_PREVENT_SLEEP=0
;; => nil                                        ; unsupported platform or missing binaries

This inspection reflects the same logic used when start-handoff-daemon! builds the final launch command: (into (vec (sleep-inhibitor-prefix)) …).

Platform Behavior Summary

Platform	Mechanism	Binary Dependencies	Sleep Types Blocked
macOS	caffeinate -dims	caffeinate (built-in)	Idle, display, disk, system
Linux	systemd-inhibit	systemd-inhibit, systemctl, running systemd	Suspend, idle
Other	None	N/A	N/A

Summary

• SwarmForge sleep inhibitor is implemented in swarmforge/scripts/swarmforge.bb via the sleep-inhibitor-prefix function
• macOS uses caffeinate -dims to prevent all sleep types while the handoff daemon runs
• Linux uses systemd-inhibit --what=sleep:idle when systemd is available and running
• Disable by setting SWARMFORGE_PREVENT_SLEEP=0 before launching ./swarm
• The inhibitor prefix is injected by start-handoff-daemon! when building the final daemon command vector

Frequently Asked Questions

What happens if caffeinate or systemd-inhibit is not installed?

If the required binary is missing, sleep-inhibitor-prefix returns nil and the handoff daemon starts without sleep inhibition. SwarmForge will not fail or warn; the swarm simply runs with normal OS power management. On macOS, caffeinate is part of the standard installation. On Linux, systemd-based distributions typically include systemd-inhibit by default.

Does the sleep inhibitor affect SwarmForge's child processes or just the daemon?

The inhibitor only wraps the handoff daemon process started by start-handoff-daemon!. The daemon itself manages agent workers, so sleep prevention applies indirectly to the entire swarm lifecycle. Once the daemon exits—normally or abnormally—the inhibitor releases automatically.

Can I use a custom sleep inhibition command instead?

Direct configuration of a custom prefix is not exposed through environment variables. The sleep-inhibitor-prefix function has fixed platform branches. However, you could modify swarmforge/scripts/swarmforge.bb locally to extend the case statement or inject logic before start-handoff-daemon! processes the prefix.

Why does SwarmForge check linux-systemd-running? on Linux?

The additional systemd state check ensures systemd-inhibit will actually function. On systems where systemd binaries exist but systemd is not the active init (such as containers or alternative init systems), the inhibitor would fail or behave unpredictably. The linux-systemd-running? predicate guards against this by verifying the systemd status is running or degraded before attempting inhibition.

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