# Configuring Sleep Prevention Behavior Across macOS and Linux in SwarmForge

> Learn how SwarmForge prevents macOS and Linux hosts from sleeping during swarm activity. Discover the OS-specific sleep inhibitor mechanism.

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

---

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

```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")
                          (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

```bash

# 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

```bash

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

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

```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")
                          (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`](https://github.com/unclebob/swarm-forge/blob/main/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.