# How SwarmForge Prevents System Sleep During an Active Swarm

> Discover how SwarmForge prevents system sleep during active swarms by using OS-specific sleep inhibitors like caffeinate on macOS and systemd-inhibit on Linux.

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

---

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

```clojure
(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`](https://github.com/unclebob/swarm-forge/blob/main/README.md) (lines 69–70). After parsing the configuration in [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf), the launcher executes the constructed inhibitor command in the background before initializing tmux sessions:

```clojure
(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`](https://github.com/unclebob/swarm-forge/blob/main/README.md) (lines 87–88):

```bash

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