macOS - Maintenance Tasks - Upgrade Automox Agent

What the Automox Agent Upgrade Worklet does

This Automox Worklet™ compares the installed Automox Agent version against the latest stable version available from the Automox console API. If the installed version is older, the Worklet schedules a complete reinstallation using macOS launchctl to handle the process outside the agent's execution context.

The Worklet performs a semantic version comparison to accurately determine whether an upgrade is needed. It creates a launchd plist file and a shell script that runs after the Worklet completes, deregistering the agent, removing the binary, and downloading the latest installer from the Automox console.

Why upgrade the Automox Agent through a Worklet

Endpoints with very old agent versions, network restrictions, or configuration issues may not receive automatic updates, leaving them unable to execute new policies or access the latest security features. The Automox Agent typically updates itself automatically, but some situations prevent normal updates. This Worklet provides a reliable fallback mechanism when automatic updates fail.

Running the latest agent version is important for security, performance, and feature compatibility. Newer agent versions include bug fixes, security patches, and support for the latest Automox console features. Outdated agents may not function correctly with newer policies or console capabilities.

Because the agent cannot update itself while running, this Worklet uses a clever approach: it schedules the reinstallation through launchctl, which executes independently of the agent process. This allows the upgrade to proceed even though the agent must be stopped.

How Agent upgrade works

1. Evaluation phase: The Worklet queries the installed agent version using /usr/local/bin/amagent version (with a 5-second timeout to handle older agents). It then fetches the latest stable version from the Automox API at console.automox.com/api/info. A semantic version comparison determines if the installed version is older than the latest available version.

2. Remediation phase: The Worklet creates a shell script at /Library/Application Support/Automox/ax_reinstall_agent.sh that deregisters the agent, removes the binary, and downloads the latest installer using your access key. It creates a launchd plist file that executes this script after a 40-second delay. The plist is loaded via launchctl, and the reinstallation completes within 1-2 minutes.

Agent upgrade requirements

• macOS endpoint (workstation or server)

• Automox Agent version 1.40.0 or later currently installed

• Automox Zone Access Key stored as a Shared Secret named accesskey

• Network connectivity to console.automox.com for downloading the installer

Expected state after Agent upgrade

Within 1-2 minutes after the Worklet runs, the endpoint reconnects to the Automox console with the latest agent version. You can verify the upgrade by checking the agent version in the console's endpoint details or running amagent version on the endpoint. The updated agent restores full functionality including policy execution, updated feature support, and current security patches.

The temporary files created during the upgrade process (the launchd plist and shell script) are automatically cleaned up after the reinstallation completes. The endpoint maintains its zone membership and policy assignments through the upgrade process, preventing any disruption to existing configurations or scheduled Worklets.

How to validate upgrade automox agent changes

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

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 function, /usr/local/bin/amagent, break.

4. Validate remediation effects from script operations such as function, /usr/local/bin/amagent, break, then rerun evaluation for compliance.