Reboot Mac Endpoints Stuck in Needs-Restart State

What the Needs-Restart Mac reboot Worklet does

This Automox Worklet™ reboots Mac endpoints that are sitting in a Needs-Restart state after a pending macOS update, configuration profile change, or system framework install. The Worklet inspects the macOS restart-required signal with a combination of /usr/libexec/PlistBuddy reads against /Library/Updates/index.plist and a check for the /var/db/.AppleUpgrade flag file. If either signal indicates a pending restart, the Worklet schedules a graceful shutdown -r now to complete the pending change.

The Worklet is deliberately narrow. It only reboots when a Needs-Restart signal is true; it does not reboot on a schedule, on demand, or as a side effect of any other check. Endpoints with no pending restart pass evaluation at exit code 0 and remediation is skipped, so the policy can sit against every Mac group without risking surprise reboots on endpoints that are not actually waiting on an update. The Worklet logs the inspected signals so an admin can see why a given endpoint did not get rebooted.

Because the evaluation phase only reads the macOS Needs-Restart signal and does not modify state, the policy can run on a tight schedule (every few hours during a patch rollout is a common choice). Each run catches endpoints that have just landed in a Needs-Restart state since the previous evaluation and reboots them within the configured maintenance window. End user notification can be layered on through a configuration parameter that toggles a Notification Center prompt before the shutdown command fires.

Why force the pending Mac reboot at fleet scale

Modern macOS updates often complete in two phases: a download-and-stage phase that runs in the background while the user keeps working, and a reboot-and-install phase that requires the endpoint to come down. Users defer that second phase. They close the prompt, click "later tonight," then leave their laptop sleeping. Days later, the patch is still pending, the security team's exposure dashboard still shows the endpoint as vulnerable, and the original update has been superseded by an even newer release that the endpoint also cannot install until the first reboot completes.

Scheduling this Worklet on a recurring policy during an approved maintenance window closes the patching loop on Mac endpoints whose users have been deferring the restart prompt. The evaluation phase reads /Library/Updates/index.plist and the /var/db/.AppleUpgrade flag on every Mac in scope, and only the endpoints with a true Needs-Restart signal get the shutdown -r command. A staged macOS update that has been pending for a week on an executive laptop, a developer Mac that missed the original prompt, and a kiosk Mac that has not been logged into in days all land their pending update in the same policy run. Pair this Worklet with a maintenance-window scheduling policy so the reboot only fires during a window the operations team has approved.

How the Mac reboot trigger works

1. Evaluation phase: The Worklet reads the macOS restart-required signal by checking /Library/Updates/index.plist with /usr/libexec/PlistBuddy and by testing for the presence of /var/db/.AppleUpgrade and /var/db/.SoftwareUpdateAtLogout. If any of those signals indicate a pending restart, the endpoint is flagged for remediation. The evaluation also reads pmset -g batt to confirm the endpoint is on AC power (configurable via an AllowBatteryReboot parameter) before approving the reboot.

2. Remediation phase: The remediation script issues sudo shutdown -r +1 "Automox is restarting this Mac to complete a pending update" to give the user a one-minute notification before the reboot. If the AllowImmediate parameter is set to true, the script falls back to sudo shutdown -r now without the notification. Exit 0 once the shutdown command is queued; non-zero with a descriptive message in stderr if the shutdown command was rejected (for example because the endpoint is on battery and AllowBatteryReboot is false).

Needs-Restart reboot requirements

• Mac endpoint running macOS 11 Big Sur or later with the standard /usr/libexec/PlistBuddy and pmset binaries available

• Root or sudo privileges for the Automox agent (the default agent context already meets this) to issue the shutdown command

• A scheduled maintenance window aligned with the policy schedule so reboots fire outside of active user sessions

• AllowBatteryReboot parameter set to match the operations runbook; the default is false to avoid rebooting an offline laptop into a flat-battery state

• End user notification or runbook entry explaining that the Mac may reboot on its own when an update has been pending too long; this is the single biggest source of "why did my Mac just restart" tickets if the rollout is not communicated

Expected state after the reboot lands

After successful remediation, the Mac endpoint reboots, the pending update or configuration change completes during the boot sequence, and the Needs-Restart signal clears. Subsequent Automox policy runs report the endpoint as compliant unless a new update has landed since the reboot and triggered a fresh Needs-Restart state. The activity log captures both the pre-reboot inspection (which signals triggered the reboot) and the post-reboot agent re-check-in time.

Validate by checking the activity log for the timestamp of the shutdown command, then comparing to the endpoint's first post-reboot agent check-in. For audit evidence, capture both timestamps along with the macOS version before and after the reboot so the update install can be tied to a specific policy run. Endpoints that report Needs-Restart but never reboot usually fail the AllowBatteryReboot gate, are inside an exclusion group, or have an active user session that the runbook has configured to block reboots; investigate those before assuming the Worklet itself has failed.