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

> Learn how the SwarmForge sleep inhibitor works on macOS and Linux, discover its OS-specific commands, and easily disable it by setting SWARMFORGE_PREVENT_SLEEP=0.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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.

```clojure
(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:

```bash
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

```bash

# 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:

```clojure
(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.