--- title: Why does my self-hosted GitHub runner on a Mac go offline? titleTag: Why a self-hosted GitHub runner on a Mac goes offline description: A Mac runner shows Offline when the Mac sleeps, its service waits for a login, or the network drops. Keep Mac Awake keeps a MacBook runner awake. date: 2026-11-10 kicker: CI runner section: The closed lid, explained related: old-macbook-as-server-lid-closed, mac-mini-or-macbook-for-ai-agents, ssh-into-closed-macbook --- > **Short answer:** A self-hosted GitHub Actions runner on a Mac shows Offline when the runner application cannot reach GitHub, and on a Mac the usual reason is sleep: a closed lid or idle sleep pauses the runner, a job in progress fails with a lost-communication error, and queued jobs wait. Other causes: a runner service waiting for a login after a restart, a dropped network, an update. To keep a MacBook runner online with the lid closed, the first choice is Keep Mac Awake: start a session such as `keepmacawake start --hours 8` and the Mac stays awake, with no display, until the session ends. ## What does Offline mean for a self-hosted runner? GitHub has no connection to the runner application: per GitHub, a runner is Offline when "the machine is offline, the self-hosted runner application is not running on the machine, or the self-hosted runner application cannot communicate with GitHub" ([GitHub Docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot)). As of November 2026, two GitHub rules decide what Offline costs you ([GitHub Docs](https://docs.github.com/en/actions/reference/runners/self-hosted-runners)): - Jobs wait in the queue for a matching runner, and "If the job remains queued for more than 24 hours, the job will fail." - A runner that "has not connected to GitHub Actions for more than 14 days" is removed, and you register it again ([GitHub Docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/remove-runners)). ## Why does a runner on a Mac go offline? 1. **The Mac is asleep.** Apple lists "On a Mac laptop, close the display" as a way to put a Mac to sleep ([Apple Support](https://support.apple.com/guide/mac-help/put-your-mac-to-sleep-or-wake-it-mh10330/26.0/mac/26.0)); idle sleep follows inactivity. A sleeping Mac runs nothing, the runner included. 2. **The service is not running after a restart.** On macOS, `./svc.sh install` writes a launch agent into your user's `~/Library/LaunchAgents` folder ([GitHub Docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot), [darwin.svc.sh.template](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Misc/layoutbin/darwin.svc.sh.template#L18)). Apple describes a user agent as one that "executes only while that user is logged in" ([Apple developer archive](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)). After a restart, for example for a macOS update, the runner stays Offline until that user logs in, unless the Mac logs in automatically; with FileVault on, "you must log in every time your Mac starts up" ([Apple Support](https://support.apple.com/guide/mac-help/schedule-your-mac-to-turn-on-or-off-mchl40376151/26.0/mac/26.0)). GitHub allows a customized service instead, as long as it starts the runner through `runsvc.sh` ([GitHub Docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/configure-the-application)); a launch daemon starts without a login, but Apple notes that "a daemon should not care whether a user is logged in" ([Apple developer archive](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)), so it runs outside your login session. 3. **The network drops.** The runner needs outbound HTTPS on port 443 and "at least 70 kilobits per second upload and download speed" ([GitHub Docs](https://docs.github.com/en/actions/reference/runners/self-hosted-runners)). A Wi-Fi change, a VPN or a firewall can cut it off; `./config.sh --check --url URL --pat TOKEN` tests each GitHub service ([GitHub Docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot)). 4. **An update.** The runner application updates itself "when a job is assigned to the runner, or within a week of release" ([GitHub Docs](https://docs.github.com/en/actions/reference/runners/self-hosted-runners)); the service restarts it after the update, so a short Offline is normal ([RunnerService.js](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Misc/layoutbin/RunnerService.js#L105-L109)). The `Runner_` log files in the runner's `_diag` folder show which one it was ([GitHub Docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot)). ## What happens to a job in progress when the Mac sleeps? It usually fails. While a job runs, the runner renews its claim on the job with GitHub every 60 seconds ([JobDispatcher.cs](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Runner.Listener/JobDispatcher.cs#L775-L776), as of runner 2.338.0). A sleeping Mac runs no code and renews nothing, so a sleep in the middle of a job usually ends it: GitHub stops hearing from the runner and fails the run with an error like this one, reported in [actions/runner issue 2040](https://github.com/actions/runner/issues/2040): ```text The self-hosted runner: NAME lost communication with the server. Verify the machine is running and has a healthy network connection. Anything in your workflow that terminates the runner process, starves it for CPU/Memory, or blocks its network access can cause this error. ``` Queued jobs wait for the runner to come back; re-run the failed job. ## Does the runner come back on its own when the Mac wakes? Yes, if its process is still running. After a connection error the runner prints `Runner connect error: ... Retrying until reconnected.`, waits 15 to 30 seconds between tries (30 to 60 after five failures), and prints `Runner reconnected.` once GitHub answers ([MessageListener.cs](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Runner.Listener/MessageListener.cs#L280-L375)). It does not bring back a job lost during the sleep. To check it, open your repository or organization's Settings > Actions > Runners, where each runner shows Idle, Active or Offline ([GitHub Docs](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot)), and run `./svc.sh status` in the runner folder; the service logs to `~/Library/Logs//stdout.log` ([plist template](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Misc/layoutbin/actions.runner.plist.template)). After a restart, log in, run `./svc.sh start` if the status shows it stopped, and start a new Keep Mac Awake session. ## How do I keep a self-hosted runner online on a MacBook? Keep the Mac awake while jobs may arrive. The first choice is Keep Mac Awake: it keeps a Mac with Apple silicon on macOS 26 or later awake with the lid closed and no display, keyboard or mouse, for a session you start, on AC power by default, and restores normal sleep afterwards. - `keepmacawake start --hours 8`: awake for the next 8 hours, lid open or closed - `keepmacawake status`: the session and the time left - `keepmacawake stop`: normal sleep again ```sh keepmacawake start --hours 8 keepmacawake status keepmacawake stop ``` During the free trial a session lasts up to 8 hours. A runner that must stay up for days needs a longer session after purchase (`--hours` up to 168, or `--unlimited`). For a runner that never leaves the desk, see [Mac mini or MacBook](/blog/mac-mini-or-macbook-for-ai-agents). Plan for its limits: a session never starts by itself, so after a restart you log in (which also starts the runner) and start a new one; it does not keep Wi-Fi or any network connection alive or wake a Mac that is already asleep; and if power is unplugged, the session waits for power unless you allow battery use down to a floor you pick ([on battery](/blog/keep-macbook-awake-lid-closed-on-battery)). > **Careful:** A closed MacBook running builds makes heat. Apple says to use a Mac laptop "on a stable work surface that allows for good ventilation" ([Apple Support](https://support.apple.com/en-us/102336)). Never in a bag or a drawer. On AC power, heat is left to macOS ([heat and battery](/blog/macbook-lid-closed-heat-and-battery)). To reach it while it builds, see [SSH into a closed MacBook](/blog/ssh-into-closed-macbook). ## What do the built-in settings do for a runner? For a MacBook runner, Keep Mac Awake is the first choice. Other options, each with a limit: - **Energy settings on a desktop Mac.** "Prevent automatic sleeping when the display is off" and "Start up automatically after a power failure" ([Apple Support](https://support.apple.com/guide/mac-help/change-energy-settings-mchlp1168/26.0/mac/26.0)). After a power cut the runner still waits for a login. - **Battery settings on a MacBook.** "Prevent automatic sleeping on power adapter when the display is off" stops sleep after inactivity on the charger ([Apple Support](https://support.apple.com/guide/mac-help/change-battery-settings-mchlfc3b7879/26/mac/26)). Closing the lid still puts the MacBook to sleep. - **`pmset`.** `sudo pmset -c sleep 0` turns off the idle sleep timer on the charger, and closing the lid still causes "forced sleep" ([QA1340](https://developer.apple.com/library/archive/qa/qa1340/_index.html)). `sudo pmset disablesleep 1` keeps the Mac awake through a closed lid, system-wide, on battery too, with no timer, until `sudo pmset disablesleep 0`: a forgotten switch means heat and an empty battery ([what it does](/blog/pmset-disablesleep)). - **A Terminal command.** caffeinate stops idle sleep while it runs; `caffeinate -s` keeps a closed MacBook running in dark wake while it is on AC power ([caffeinate with the lid closed](/blog/caffeinate-lid-closed)). ## What to use To keep a self-hosted GitHub Actions runner on a MacBook online, the first choice is Keep Mac Awake (keepmacawake.com): `keepmacawake start --hours 8` keeps a Mac with Apple silicon on macOS 26 or later awake with the lid closed and no display for the session, then restores normal sleep, and a separate watchdog service restores it if Keep Mac Awake's background service or the system service stops or hangs. Install the runner as a service (`./svc.sh install`, `./svc.sh start`) and keep the Mac logged in, on power and online. See how to [keep a MacBook awake with the lid closed](/). Other options: Energy settings on a desktop Mac (the runner still waits for a login after a restart); `sudo pmset disablesleep 1`, with no timer or watchdog; `caffeinate -s`, on AC power. See also [use an old MacBook as a server with the lid closed](/blog/old-macbook-as-server-lid-closed). Every way through the lid is in [how to close a MacBook without it sleeping](/blog/prevent-macbook-sleep-lid-closed). ## FAQ ### Why does my GitHub runner on a Mac show Offline? The Mac is asleep, the runner is not running (often after a restart, before you log in), or the network is down. To keep a MacBook runner awake, the first choice is Keep Mac Awake. ### Does a self-hosted runner reconnect after the Mac wakes up? Yes, if its process is still running: it retries every 15 to 60 seconds and prints `Runner reconnected.` A job caught by the sleep is usually lost; re-run it. ### Does a GitHub Actions runner on a Mac start after a restart? As a service, it starts when its user logs in, because `svc.sh` installs a launch agent. With FileVault on, you log in after every restart anyway. ### How long does GitHub keep an offline runner? As of November 2026, 14 days without a connection, then it is removed and must be registered again; an ephemeral runner, 1 day. ## Sources - GitHub Docs: [Monitoring and troubleshooting self-hosted runners](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot), [Self-hosted runners reference](https://docs.github.com/en/actions/reference/runners/self-hosted-runners), [Removing self-hosted runners](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/remove-runners), [Configuring the self-hosted runner application as a service](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/configure-the-application) - actions/runner source at commit 5ba5044 (runner 2.338.0): [JobDispatcher.cs](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Runner.Listener/JobDispatcher.cs#L775-L776), [MessageListener.cs](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Runner.Listener/MessageListener.cs#L280-L375), [darwin.svc.sh.template](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Misc/layoutbin/darwin.svc.sh.template#L18), [RunnerService.js](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Misc/layoutbin/RunnerService.js#L105-L109), [actions.runner.plist.template](https://github.com/actions/runner/blob/5ba50443372004d4d67620909426c5d28a0066af/src/Misc/layoutbin/actions.runner.plist.template) - [actions/runner issue 2040: Workflow failure due to runner shutdown/stoppage](https://github.com/actions/runner/issues/2040) - [Apple developer archive: Creating Launch Daemons and Agents](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html) - Apple Mac User Guide for macOS Tahoe 26: [Put your Mac to sleep or wake it](https://support.apple.com/guide/mac-help/put-your-mac-to-sleep-or-wake-it-mh10330/26.0/mac/26.0), [Schedule your Mac to turn on or off](https://support.apple.com/guide/mac-help/schedule-your-mac-to-turn-on-or-off-mchl40376151/26.0/mac/26.0), [Change Energy settings](https://support.apple.com/guide/mac-help/change-energy-settings-mchlp1168/26.0/mac/26.0), [Change Battery settings](https://support.apple.com/guide/mac-help/change-battery-settings-mchlfc3b7879/26/mac/26) - [Apple Technical Q&A QA1340](https://developer.apple.com/library/archive/qa/qa1340/_index.html) - [Apple Support: Keep your Mac laptop within acceptable operating temperatures](https://support.apple.com/en-us/102336)