Before you begin
- Atlas Reach enabled for the tenant, with the Atlas Reach agent installed and the device approved
- The reach.view permission to read the Agent updates tab, and reach.deploy to start an update. Every reach.* permission belongs to the built-in administrator role only, and you can add them to a custom role
How updates are checked and installed
Every agent checks for an update once a day. When your deployment offers a newer version for the device's operating system and architecture, the agent downloads it, verifies its SHA-256 hash, and installs it. A package whose hash does not match is never installed.
- Windows: the MSI for the device's architecture (x64, x86 or ARM64).
- macOS: the signed universal .pkg, installed with the system installer.
- Linux: the .deb or .rpm package, installed by the system package tool.
Agents never downgrade on their own: a device only installs a version newer than the one it runs. The device drops offline for a moment while it installs and reconnects on the new version.
Staged rollout
A new agent build is not offered to every device at once. On Windows, macOS and Linux alike, it reaches 5% of your devices on its first day, 25% on its second, and every device after that. Each device's place in the rollout is fixed for that version, so a widening stage only adds devices, and each release starts on a different slice of the fleet. A device the new build has not reached yet shows Rolling out in the Devices grid. It is still offered the newest earlier build that has reached it, so it never falls far behind, and an admin can install the new build on it right away (see below).
Windows: automatic rollback
Before a Windows agent updates, it keeps a copy of the version it is replacing. If the new version has not reconnected to Atlas AVD within about 15 minutes, the device reinstalls the previous version on its own and skips that build on its daily check until a newer one is published.
- If the device cannot reach Atlas AVD on the old version either, the problem is the network rather than the update, so it waits up to 4 hours before it decides.
- When several devices roll the same build back, that build stops being offered to anyone. Devices that have not taken it are offered the previous build instead.
- The first self-update after an agent was installed by hand or with Intune has no earlier package to fall back to. Every update after that can be rolled back.
To put a Windows device back on an earlier agent yourself, deploy the earlier MSI through Intune, your RMM tool or msiexec. Settings carry forward, so no extra properties are needed.
macOS and Linux
macOS and Linux agents update themselves the same way, from the package your deployment publishes for them, and a new build reaches them through the same staged rollout. They do not roll themselves back: to return one to an earlier version, reinstall that package through your package manager or MDM.
- A Linux device without systemd, or an agent that was not installed from its package, cannot install updates itself. Asking it to update shows "This agent cannot self-update"; upgrade it through your package manager or MDM.
- macOS and Linux agents follow their own version line, separate from the Windows agent, so their version numbers differ.
See what changed: the Agent updates tab
Go to Atlas Reach → Agent updates to read the agent's release notes, newest release first. Pick Windows, macOS or Linux to see that platform's notes. The release your deployment currently offers is marked Offered now, and the top of the page says which version that platform's devices are offered.
- In the Devices grid, a device running an older agent shows an Update available badge. Click it to open the Agent updates tab for that device: the releases it gains by updating are marked New for <device name>, and Update now updates it straight away.
- Each release's notes are grouped into Features, Improvements, Bug Fixes and Chores.
The Agent updates tab is a changelog only. It has no rollout rings, channels or version pins to set. Holding or pinning an agent version is a deployment-level setting, made in your Atlas AVD deployment's configuration, not in the app.
Update now instead of waiting
You can tell a device to run its update check immediately. Both ways need the reach.deploy permission.
- One device: use the update action on the device's row in Atlas Reach → Devices, or Check for agent update on the device's page. Atlas tells you whether the agent started updating, was already up to date, or could not update.
- Many devices: select them in the Devices grid and choose Update Atlas agent from the toolbar. Each eligible device runs its check now, and a device that is behind installs the published agent and reconnects on the new version.
- On a schedule: create an Automation schedule with the Agent self-update check action.
- Ahead of the staged rollout: a device marked Rolling out is not offered the new build yet, so checking it now does not install it. An administrator can skip the wait with Install update now, either from that device's row menu or its page, or for every Rolling out device at once with the Install update now button in the Devices toolbar. The update is still verified before it installs, and each device it is released to is recorded in the audit log.
An update check you start yourself installs the build your deployment offers that device, even one the device rolled back earlier. It does not override a hold set on the deployment.
Turn self-update off for a device
If you roll out agent versions with your own tooling, install the agent with auto-update off: ATLAS_AUTO_UPDATE=0 on Windows, or autoUpdate set to false (or ATLAS_AUTO_UPDATE=0) in the agent's configuration on macOS and Linux. That device then never installs an update by itself, and asking it to update shows "Self-update is disabled on this device". Push new versions through Intune, your MDM or your package repository instead.