macOS - Maintenance Tasks - Upgrade Automox Agent

What the macOS agent upgrade Worklet does

This Automox Worklet™ brings the Automox Agent on a macOS endpoint to the latest stable release without waiting for the agent's own self-update cycle. The evaluation script reads the installed version from /usr/local/bin/amagent, queries the current stable release from the Automox console, and performs a semantic version comparison. If the endpoint is behind, the remediation script stages a launchd job that downloads the latest installer pkg, unloads the running agent, installs the new build, and reloads the LaunchDaemon.

The reinstall runs outside the agent process by design. amagent cannot replace its own binary while it is executing, so the Worklet writes /Library/Application Support/Automox/ax_reinstall_agent.sh and a companion LaunchDaemon plist, then loads the plist with launchctl. The plist fires roughly 40 seconds after the Worklet exits, which lets Automox record the policy result, then the script handles the deregister, pkg install, and relaunch sequence. The endpoint reappears in the console under the same zone, same groups, and same policies within one to two minutes.

The script reads the Automox Zone Access Key from a Shared Secret named accesskey so the new installer can authenticate the endpoint back into the same zone. Because evaluation is a pure version check, the Worklet is idempotent: once an endpoint is on the latest release the next policy run reports compliant and remediation is skipped.

Why force an Automox Agent upgrade on Mac endpoints

The Automox Agent on macOS normally upgrades itself in place, but the self-update path is fragile in a way that is easy to miss at scale. A Mac that is off the network during the update window, a corporate proxy that blocks the installer CDN, a stalled launchctl bootstrap on Apple Silicon, or an agent build older than 1.40.0 will all silently leave an endpoint behind. The longer an agent lags, the more new policy features (FixNow, newer Worklet APIs, current TLS ciphers, refreshed signing certificates) it cannot honor. Endpoints stuck on a pre-1.40 build cannot even reach the modern updater path on their own.

A Mac stuck on an older Automox Agent build is a blind spot in your patch posture, since policy evaluations may not honor the latest scheduling and prerequisite logic. This Worklet acts directly on the endpoint, hands the upgrade to launchd so the agent can swap itself, and brings every lagging Mac back to a known-good baseline before the next patch window opens.

How the launchd-driven agent upgrade works

1. Evaluation phase: The Worklet runs /usr/local/bin/amagent --version (wrapped in a 5-second timeout so a hung binary cannot stall the policy) and parses the installed semantic version. It then issues an HTTPS request to https://console.automox.com/api/info to read the current stable release. A version-tuple comparison decides the result: equal or newer exits 0 (compliant); older exits non-zero (non-compliant) and triggers remediation. If amagent is missing or unreadable, the Worklet reports the failure in stderr so the activity log surfaces it instead of silently skipping the endpoint.

2. Remediation phase: The Worklet writes /Library/Application Support/Automox/ax_reinstall_agent.sh, which calls amagent --deregister, removes the existing binary tree under /usr/local/bin/amagent and /Library/LaunchDaemons/com.automox.agent.plist, downloads the latest signed pkg from the Automox console using the accesskey Shared Secret, runs installer -pkg /tmp/automox-installer.pkg -target /, and finally issues launchctl load /Library/LaunchDaemons/com.automox.agent.plist to bring the new agent online. A companion LaunchDaemon plist schedules that script to fire about 40 seconds after the Worklet exits, so the policy result is recorded before the agent stops itself. Temporary files are cleaned up by the script's own trap on exit.

Agent upgrade requirements on macOS

• macOS endpoint with the Automox Agent already installed at version 1.40.0 or later (older builds cannot reach the modern installer endpoint and need to be reinstalled manually first)

• Both Intel and Apple Silicon Macs are supported; the installer pkg is universal

• Root context for the Automox Agent (the default LaunchDaemon execution context already satisfies this; no extra privileges to grant)

• Outbound HTTPS reachability from the endpoint to console.automox.com for the version probe and pkg download

• The endpoint's Automox Zone Access Key stored as a Shared Secret named accesskey on the policy so the new install authenticates back into the original zone

• Avoid stacking this policy with concurrent patch or restart Worklets in the same run window; let the reinstall finish before the next agent task executes

Expected state after the Automox Agent upgrade

Within one to two minutes of the Worklet exiting, the endpoint reappears in the Automox console reporting the latest stable agent version, in the same zone, with the same groups, policies, and Worklet assignments it had before. The LaunchDaemon at /Library/LaunchDaemons/com.automox.agent.plist is reloaded and running under root. /usr/local/bin/amagent --version returns the new build number, and the next policy evaluation cycle picks up immediately. Subsequent runs of this Worklet exit 0 and do not retrigger the reinstall, because the version check now matches.

Validate by running /usr/local/bin/amagent --version on the endpoint and confirming it matches the version shown in the Automox console for that host. Check the activity log for two policy events: the original non-compliant evaluation and the follow-up compliant evaluation after the next agent check-in. The temporary helper files (/Library/Application Support/Automox/ax_reinstall_agent.sh, the staged LaunchDaemon plist, and /tmp/automox-installer.pkg) are removed by the reinstall script on exit, so /Library/Application Support/Automox/ should return to its baseline state. If the endpoint does not reappear within five minutes, inspect /var/log/install.log for installer pkg errors and /Library/Logs/Automox/ for agent startup messages.