macOS - Tray Notification - Customize Branding Icon

What the Automox Agent icon branding Worklet does

This Automox Worklet™ replaces the default Automox Agent tray icon on macOS endpoints with your organization's branded icons. The Worklet reads two PNG files attached to the Worklet as payloads – darkModeIcon.png and lightModeIcon.png – and applies them through the amagent notifications set_icon command. The macOS menu bar picks up the new icons immediately, with no logout or reboot.

Both files must be PNG at 256 by 256 pixels. The dark mode icon shows when macOS is in dark appearance and the light mode icon shows in light appearance. macOS swaps between them automatically when the end user toggles System Settings → Appearance.

Before applying icons, the Worklet checks that Automox Agent 2.5.0 or higher is installed. Older agents do not expose the notifications set_icon subcommand, so the evaluation script exits cleanly on those endpoints instead of failing the policy run. The Worklet is FixNow compatible, so you can pilot a new brand on a single Mac before scheduling a full-fleet policy.

Why enforce a branded tray icon across managed Macs

The Automox Agent tray icon is one of the few daily touchpoints between IT and the end user on a Mac. Without enforcement, branding drifts: a pilot group gets the new mark, a re-imaged laptop comes back with the default Automox logo, and an acquired department still shows the old corporate icon. Your end users open tickets asking whether the agent in their menu bar is legitimate, and the help desk burns cycles confirming what a branded icon should make obvious.

Run on a recurring policy, this Worklet catches reverted endpoints – freshly imaged, restored from backup, or rolled back by an agent reinstall – before an end user notices. Each evaluation either confirms the endpoint is on a current agent and reapplies the branded payload, or marks the endpoint as ineligible so you can target it for an agent upgrade.

How Automox Agent icon branding works

1. Evaluation phase: The Worklet checks for the Automox Tray application at /Library/Application Support/Automox/agent-ui.app or /Library/Application Support/Automox/agent-ui. It then confirms /usr/local/bin/amagent exists and runs amagent version under a five second timeout to capture the installed agent version. A semantic version comparison against 2.5.0 decides eligibility. Endpoints without the tray, without amagent, where the version probe times out, or below 2.5.0 exit 0 and are skipped. Eligible endpoints exit 2, which schedules remediation.

2. Remediation phase: The remediation script re-runs the agent version gate as a safety check, then validates that the payload filenames end in .png. It calls /usr/local/bin/amagent notifications set_icon --darkmode "$PWD/darkModeIcon.png" --lightmode "$PWD/lightModeIcon.png". The agent applies the icons to the menu bar immediately with no service restart. A successful set returns exit code 0 and logs "Successfully set branding icon." A missing or out-of-date amagent returns exit code 1. A PNG validation failure or an amagent error returns exit code 2, with the message written to stderr so it surfaces in the Automox activity log.

Branded tray icon requirements

• macOS endpoint with Automox Agent 2.5.0 or higher installed and the amagent binary at /usr/local/bin/amagent

• Automox Tray application present at /Library/Application Support/Automox/agent-ui or /Library/Application Support/Automox/agent-ui.app

• Two PNG icon files at 256 by 256 pixels: one dark mode variant and one light mode variant. SVG and ICNS are not supported

• Icon files attached to the Worklet as payloads named darkModeIcon.png and lightModeIcon.png. The remediation script reads both from $PWD at run time

• Root execution context for the Automox agent. The default agent context on macOS already meets this requirement

• A companion Worklet, Reset Branding Icon for macOS, is available when you want to revert an endpoint to the default Automox icon

Expected tray icon state after remediation

After the Worklet completes successfully, the Automox Agent icon in the macOS menu bar shows your branded design. macOS swaps automatically between the dark and light variants as the end user toggles System Settings → Appearance. The Automox activity log records exit code 0 along with "Successfully set branding icon."

On endpoints that did not clear the agent version gate, the activity log records the detected version, notes that Agent 2.5.0 or higher is required, and reports that remediation was skipped. Those endpoints stay on the default icon until the agent is upgraded, and the next scheduled evaluation picks them up. On a recurring policy, any endpoint that loses the icon through an agent reinstall, a system restore, or a re-image returns to the branded state on the next run, without an admin touching the Mac.