> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guardway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent updates

> How enrolled machines move to a new Guardway agent release — the console policy, what the updater does on each operating system, and how to update by hand.

## What this is for

Once a machine reports, you never have to touch it to keep its agent current. The **Agent updates**
section of its [Endpoint AI Policy](/endpoint-ai-risk/policy#agent-updates) sets whether machines
install updates themselves, how far behind the newest release they stay, and when they may do it.
This page explains what happens on the machine.

## The policy

| Setting | Default |
| - | - |
| **Update mode**: Off, Notify, Auto-install | Notify |
| **Version strategy**: always latest, N releases behind, pinned, stable channel | Two releases behind |
| **Minimum version** | None |
| **Soak before adopting** | 72 hours |
| **Rollout ring** | 100% |
| **Maintenance window** | Any time |

Under **Notify**, Fleet shows which machines have an update available in the **Sensor** column and
nothing is installed. Under **Auto-install**, each machine installs the release the policy selects,
with nobody present, inside its maintenance window. The agent only installs releases from Guardway's
signed release index, never downgrades itself, and checks that the new version is serving before it
finishes.

## What runs on the machine

| OS | Updater | What it installs | Rollback |
| - | - | - | - |
| macOS | LaunchDaemon `ai.guardway.gw-cli.updater`, every 15 minutes | The new binary into `/usr/local/bin`, then restarts every agent | Automatic if the new version does not serve |
| Windows (managed) | Scheduled task **Guardway gw-cli updater**, every 15 minutes | The new binary under `C:\ProgramData\Guardway\bin` and the Program Files copy | Automatic |
| Windows (observe, MSI only) | None | Deploy the next MSI, or run `gw-cli upgrade` | n/a |
| Linux, package install | systemd timer `guardway-gw-cli-updater.timer`, every 15 minutes | The `.deb` or `.rpm` for the release, through `dpkg` or `rpm`, so the package database stays right | None; a version that does not start is reported as needing attention |

Check a machine with:

```sh theme={null}
gw-cli update --check --refresh     # the console's verdict, the policy, the window, who installs here
```

## Updating by hand

Installing the next package over the current one is always supported and keeps the mode,
enrollment and data: `installer -pkg` on macOS, `msiexec /i` on Windows, `apt install` or
`dnf upgrade` on Linux. `sudo gw-cli upgrade` follows the policy's target on macOS and Windows;
on a Linux package install it prints the `apt` or `dnf` command instead of replacing the binary.

## One-time bootstrap

Machines on old agents have no updater yet:

* macOS and Windows managed installs older than the updater: install the current package once.
* Windows MSIs older than 0.2.148 and Linux packages older than 0.2.160 cannot update themselves: install the current package over them once.

After that the console policy governs.

## Limits

* A release that changes the code-signing identity on macOS is never installed unattended, because it would void Full Disk Access. It needs the package or `sudo gw-cli upgrade`.
* A per-user archive install has no machine-wide updater; update it with `gw-cli upgrade`.
* Homes on an external or network volume on macOS need Full Disk Access for the updater.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.