Upgrade macOS

What the macOS upgrade Worklet does

This Automox Worklet™ performs in-place operating system upgrades on macOS endpoints to versions like Monterey, Big Sur, Catalina, Mojave, or High Sierra. The Worklet checks the Darwin version number to determine the current macOS version, then launches the upgrade process using a cached installer stored in the Applications folder.

The Worklet adapts its behavior based on the processor architecture. Intel-based Macs complete fully automated upgrades using the startosinstall command with unattended installation flags. Apple Silicon Macs require authentication from an admin with a secure token, so the Worklet opens the cached installer application to prompt the end user to proceed with the upgrade.

Before initiating any upgrade, the Worklet validates that the installer exists at the expected path, checks for AC power connection, and verifies sufficient free disk space on the root volume. The script requires at least 26 GB of free space by default, matching Apple's minimum requirements for major macOS upgrades.

Why standardize macOS versions across your fleet

Keeping macOS endpoints on consistent operating system versions simplifies security patch management and reduces compatibility issues. When your Mac fleet runs mixed macOS versions, you face challenges deploying software that requires specific OS versions, managing security baselines, and troubleshooting user issues that vary by OS version.

Major macOS upgrades deliver critical security enhancements that older versions cannot receive. Apple focuses security updates and vendor support on recent macOS versions, typically the current release and two previous major versions. Running outdated macOS versions exposes endpoints to unpatched vulnerabilities and limits your ability to deploy modern security tools.

Automating macOS upgrades through this Worklet saves IT operations teams time compared to manually upgrading individual endpoints or creating custom deployment workflows. The Worklet handles prerequisite validation, manages the upgrade process, and notifies users on Intel Macs before the required reboot.

How macOS version upgrades work

1. Evaluation phase: The Worklet uses uname -r to check the Darwin version number and compares it against the target macOS version. Darwin version 21 corresponds to Monterey, 20 to Big Sur, 19 to Catalina, 18 to Mojave, and 17 to High Sierra. If the endpoint already runs the target version, the evaluation exits successfully without triggering remediation.

2. Remediation phase: The Worklet validates that the installer exists at /Applications/Install macOS [Version].app, confirms AC power connection, and checks for sufficient free disk space. On Intel Macs, the Worklet runs startosinstall --agreetolicense --rebootdelay to perform an unattended upgrade with a configurable reboot delay and user notification. On Apple Silicon Macs, the Worklet launches the installer application for the logged-in user to authenticate and proceed with the upgrade.

macOS upgrade requirements

• macOS installer application cached in the Applications folder before running the Worklet

• Endpoint connected to AC power during the upgrade process

• At least 26 GB of free disk space on the root volume (adjustable via the freeSpaceRequired variable)

• Apple Silicon Macs require a logged-in admin user with a secure token to authenticate the upgrade

• Modify the macOSName variable in both evaluation and remediation scripts to target different macOS versions (case-sensitive, without the "macOS" prefix)

• Update the darwinVersion comparison value to match your target macOS version

Expected endpoint state after macOS upgrade

After successful remediation, Intel-based Mac endpoints reboot automatically and complete the macOS upgrade process. You can verify this change by checking System Settings or the relevant system configuration. The endpoint runs the target macOS version specified in the macOSName variable. Users see a notification 60 seconds before the reboot occurs, giving them time to save work in progress.

Apple Silicon Mac endpoints display the installer application for the logged-in user to authenticate and initiate the upgrade. After the user provides admin credentials with a secure token, the upgrade proceeds and the endpoint reboots to complete installation. You can verify the upgrade by checking the Darwin version number or running system profiler commands to confirm the macOS version.

On Intel Macs, the Worklet creates an installation log at /var/log/[Version]Install.log that captures output from the startosinstall process. The log automatically opens in Console.app when a user is logged in, providing visibility into the upgrade progress and any errors that occur during installation.

How to validate upgrade macos changes

1. Run this Worklet on a pilot macOS endpoint and review evaluation output for upgrade macos.

2. Confirm Automox activity logs show successful completion and exit code 0.

3. Verify endpoint state using checks aligned to evaluation script logic, such as exit, else.

4. Validate remediation effects from script operations such as function, errMessage, exit, then rerun evaluation for compliance.