Upgrade macOS

What the macOS major upgrade Worklet does

This Automox Worklet™ performs an in-place major macOS upgrade on endpoints that already have the installer cached at /Applications/Install macOS [Version].app. The Worklet reads the Darwin kernel version with uname -r, compares it against the target release, and either exits cleanly or drives the upgrade to completion. The same policy works across Intel and Apple Silicon Macs because the remediation script branches on architecture at run time.

On Intel Macs the Worklet invokes the installer's startosinstall binary with --agreetolicense and a configurable --rebootdelay, then writes output to /var/log/[Version]Install.log and opens that log in Console.app for the logged-in user. On Apple Silicon, where the upgrade requires authentication from an admin with a secure token, the Worklet launches the cached installer as the console user so the upgrade prompt appears on screen. Both paths share the same prerequisite checks.

Operators stage the installer ahead of time using softwareupdate --fetch-full-installer or by deploying it through a separate Worklet or MDM payload. Once the installer is on disk, this Worklet handles the version check, the disk and power validation, the user notification, and the actual launch of startosinstall. The Worklet is intentionally narrow so the same policy can be reused for Big Sur, Monterey, Ventura, Sonoma, or Sequoia by adjusting two variables.

Why upgrade macOS at fleet scale

Apple supports the current macOS release and the two previous major versions with full security updates. Endpoints running anything older accumulate unpatched kernel, Safari, and framework vulnerabilities that no patch Worklet can backfill, because Apple does not ship those fixes for unsupported releases. A fleet on a mix of Catalina, Big Sur, and Monterey forces the security team to track three separate baselines, three separate compliance attestations, and three separate sets of compatible MDM payloads.

Apple ships a major macOS release on a yearly cadence, and the prerequisites for an unattended upgrade (free disk space, model eligibility, an AC adapter, the right softwareupdate channel) shift each year. This Worklet reaches every Mac on the policy, validates the prerequisites the upgrade requires to succeed, and either advances the endpoint to the target major release or surfaces a clear non-compliant exit code so the operator knows which laptops still need attention before the next maintenance window.

How the macOS major upgrade works

1. Evaluation phase: The Worklet runs uname -r and parses the major Darwin version with cut. Darwin 24 maps to Sequoia, 23 to Sonoma, 22 to Ventura, 21 to Monterey, 20 to Big Sur, 19 to Catalina, 18 to Mojave, and 17 to High Sierra. The script holds the target Darwin version as a numeric comparison and exits 0 (compliant) when the endpoint already runs the target release. When the version is older, the script exits 1 and Automox schedules remediation.

2. Remediation phase: The Worklet verifies the installer payload at /Applications/Install macOS [Version].app/Contents/SharedSupport/SharedSupport.dmg, confirms AC power with pmset -g ps, and reads APFSContainerFree from diskutil info -plist / to enforce a 26 GB free-space floor. On Intel hardware the script calls startosinstall --agreetolicense --rebootdelay with a pidtosignal handle so caffeinate keeps the Mac awake through the prepare phase, then triggers an Automox Notifier alert sixty seconds before reboot. On Apple Silicon the script runs launchctl asuser <uid> open -a against the cached installer so the secure-token admin can authorize the upgrade interactively. A non-zero exit with a message on stderr surfaces in Automox activity logs when any prerequisite check fails.

macOS major upgrade requirements

• Installer pre-staged at /Applications/Install macOS [Version].app, typically dropped in via softwareupdate --fetch-full-installer --full-installer-version <release> or an MDM-pushed package

• At least 26 GB of free space on the system volume (tune the freeSpaceRequired variable to match Apple's documented requirement for the target release)

• Endpoint plugged into AC power; the remediation script exits 1 if pmset -g ps does not report AC Power

• Apple Silicon (M1, M2, M3, M4) endpoints need a logged-in admin user with a Secure Token; the Worklet cannot bypass the volume owner check that Apple enforces on the Signed System Volume

• Set macOSName in both evaluation.sh and remediation.sh to the target release name (case-sensitive, without the leading "macOS")

• Update the darwinVersion comparison value in evaluation.sh to match the target release so completed endpoints stop re-triggering remediation

• Optional: Automox Notifier installed under /Library/Application Support/Automox/ to deliver the pre-reboot warning to the logged-in user

Expected endpoint state after the macOS upgrade

On Intel Macs, startosinstall completes its prepare phase, the Automox Notifier displays the configured warning, and the endpoint reboots into the target macOS release. After the post-reboot Setup Assistant finishes, uname -r returns the new Darwin version and the next Automox evaluation reports the endpoint as compliant. The installation log at /var/log/[Version]Install.log records the prepare output and any errors emitted by startosinstall, and Console.app opens that log automatically for the logged-in user.

On Apple Silicon Macs, the installer window appears on screen as the logged-in user. Once the user authenticates with a Secure Token admin account, the upgrade proceeds through prepare, restart, and the final install phases. The Worklet exits at the point of handoff to the GUI, so Automox records a successful remediation as soon as the installer launches; subsequent evaluations confirm the new Darwin version after the user completes Setup Assistant.

Validate the outcome by running sw_vers -productVersion and uname -r on a sample of upgraded endpoints, or by exporting an Automox endpoint report and filtering on the OS version column. For audit evidence, retain the contents of /var/log/[Version]Install.log alongside the Automox policy run ID. If a remediation exits 1, the stderr message identifies which prerequisite failed: missing installer, no AC power, or insufficient free space, so the operator can correct the gap and re-run the policy without manually walking the failing endpoints.