Windows - Tray Notification - Customize Branding Icon

What the Windows tray branding icon Worklet does

This Automox Worklet™ replaces the default Automox agent tray icon on Windows endpoints with a custom branded icon supplied as two PNG payloads: darkModeIcon.png and lightModeIcon.png. The Worklet calls the agent's built-in command line interface, amagent.exe notifications set_icon, with the --darkmode and --lightmode parameters. Windows applies the matching icon based on the user's current system theme, so a single policy ships both variants in one run.

Each payload must be a genuine PNG sized exactly 256 by 256 pixels. The remediation script reads the first 24 bytes of every payload to verify the PNG magic signature (137 80 78 71 13 10 26 10) and parse the IHDR width and height. A payload that fails either check writes an error and exits 2 before any agent CLI call is made. A CSV state file at C:\Program Files (x86)\Automox\tray_branding_icon_state.csv records the SHA256 hash of each applied icon, so an unchanged policy run completes in milliseconds.

The Worklet requires Automox Agent version 2.5.0 or higher. Version detection reads DisplayVersion from HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\* where DisplayName equals Automox Agent. The evaluation script exits 0 when the agent is missing or below 2.5.0 so non-applicable endpoints stay quiet; the remediation script exits 2 in the same conditions so the failure is visible in the console. To revert to the default Automox branding, deploy the companion Reset Branding Icon Worklet on the same scope.

Why enforce a consistent tray icon across the fleet

End users judge legitimacy by what they see in the system tray. An unrecognized third-party logo on a corporate laptop drives help-desk tickets, raises insider-threat false alarms, and gives employees an excuse to investigate or kill the process. A branded icon backed by the company mark turns the agent into a recognized internal tool, which lowers ticket volume and improves acceptance of automated patching and remediation delivered through the same agent.

Tray branding also matters during audits, MSP onboarding, and post-merger rebrands. The tray icon is one of the most visible artifacts of endpoint management on every desk in the company. Hunting down every Windows endpoint by hand to swap two PNG files is the kind of task that quietly stalls for months and shows up in the next IT review as drift.

Branded icons drift back to default in three predictable ways: a Windows feature update replaces the assets next to amagent-ui.exe, an agent reinstall ships the stock icons, and a tech who runs the silent installer manually skips the post-install copy. Hash comparison against the CSV state file keeps repeat policy runs cheap. Endpoints that already carry the correct PNGs finish in milliseconds; only endpoints that drifted pay the rewrite cost.

How tray icon enforcement works

1. Evaluation phase: The script first reads the Automox Agent DisplayVersion from HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\* and exits 0 if the version is below 2.5.0 or cannot be determined. It then looks for the state file at C:\Program Files (x86)\Automox\tray_branding_icon_state.csv. A missing state file exits 2 and queues remediation. If the file exists, the script imports it and confirms that the rows for darkModeIcon.png and lightModeIcon.png both carry a non-empty Hash value; a missing or empty entry also exits 2.

2. Remediation phase: The script re-verifies the agent version, confirms both payloads are present in the Worklet execution directory, clears any leftover staged files, and moves the payloads to C:\Program Files (x86)\Automox\. Each PNG passes through Test-IconFile, which reads 24 header bytes to verify the magic signature and a 256x256 IHDR. The script then computes SHA256 hashes via Get-FileHash and compares them to the state file. If hashes match, the staged copies are removed and the run exits 0 with no agent call. If hashes differ or no state file exists, the script invokes amagent.exe notifications set_icon --darkmode <path> --lightmode <path>, stops the amagent-ui process so the watchdog restarts it with the new icons, removes the staged PNGs, writes the new hashes to the CSV, and exits 0.

Tray branding requirements and payload setup

• Windows 10, Windows 11, or Windows Server 2016 and later with the Automox Agent installed

• Automox Agent version 2.5.0 or higher (detected from HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\* DisplayVersion where DisplayName equals Automox Agent)

• amagent.exe present at ${env:ProgramFiles(x86)}\Automox\amagent.exe or the 64-bit fallback at $env:ProgramFiles\Automox\amagent.exe

• PowerShell 5.1 or later for Get-FileHash, Import-Csv, and Export-Csv support

• Two PNG payloads attached to the Worklet: darkModeIcon.png (shown when Windows is set to dark mode) and lightModeIcon.png (shown when Windows is set to light mode)

• Each PNG must be exactly 256 by 256 pixels; the script reads the IHDR chunk to verify dimensions and rejects any other size

• FixNow-compatible: trigger an on-demand tray refresh against a single endpoint or a target group from the Automox console

• Local administrator context for the agent (the default Automox Agent service context already satisfies this)

Expected tray icon behavior after remediation

On a successful remediation run, the Automox tray icon briefly disappears as Stop-Process -Name amagent-ui terminates the UI; the Automox watchdog then restarts the tray within a few seconds and Windows loads the new image. Dark mode and light mode versions switch automatically when the user toggles the Windows theme, since the agent registers both variants in a single set_icon call. The CSV at C:\Program Files (x86)\Automox\tray_branding_icon_state.csv now contains two rows holding the SHA256 hash of each applied PNG.

Subsequent policy evaluations finish quickly. The evaluation script confirms the state file exists and both Hash entries are populated, then exits 0 without touching the tray. To roll a brand refresh across the fleet, upload new dark and light PNG payloads to the same Worklet and republish. The next run detects mismatched SHA256 hashes, applies the new icons, and updates the CSV. The Automox directory does not retain staged PNGs after a successful run because the script removes them once the agent CLI returns 0.

To roll back to the default Automox branding, deploy the companion Reset Branding Icon Worklet against the same target group; this Worklet has no built-in reset path. Script output and any stderr captured from amagent.exe surface in the Worklet result in the Automox console, and a non-zero exit from the agent CLI causes remediation to exit 2 with the captured error text for review.