CI runner

Why does my self-hosted GitHub runner on a Mac go offline?

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.

By , who makes Keep Mac Awake. . 7 min read. Markdown

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

As of November 2026, two GitHub rules decide what Offline costs you (GitHub Docs):

  • 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).

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); 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, darwin.svc.sh.template). Apple describes a user agent as one that "executes only while that user is logged in" (Apple developer archive). 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). GitHub allows a customized service instead, as long as it starts the runner through runsvc.sh (GitHub Docs); 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), 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). 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).
  4. An update. The runner application updates itself "when a job is assigned to the runner, or within a week of release" (GitHub Docs); the service restarts it after the update, so a short Offline is normal (RunnerService.js).

The Runner_ log files in the runner's _diag folder show which one it was (GitHub Docs).

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

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). 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), and run ./svc.sh status in the runner folder; the service logs to ~/Library/Logs/<service name>/stdout.log (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
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. 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).

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). Never in a bag or a drawer. On AC power, heat is left to macOS (heat and battery).

To reach it while it builds, see SSH into a 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). 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). 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). 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).
  • 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).

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. Every way through the lid is in how to close a MacBook without it sleeping.

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