Manage your agent fleet
The Agents page is the operations view of every Retrievy Agent installed across your workspace. Windows hosts and Docker containers land in the same list, with the same status badges, the same actions, and the same alert pipeline. This is the page you keep open while a fleet is rolling out and the page you check first when a scan goes missing.
If you're installing an agent for the first time, start with the Windows MSI install or the Docker install instead. This page documents what to do after they're running.
Before you start
- The Manage Agents permission on your role. Without it the New Token button is disabled and the destructive actions (rotate, revoke) are hidden.
- At least one agent enrolled, or a clear plan to enrol one. The page renders an empty state with a single Generate First Token call to action until your first agent appears.
- Outbound HTTPS from each agent host to your Retrievy workspace. An agent that can't reach the workspace shows up as Offline here, no matter how healthy its local host is.
Where to find it
In the left navigation, open Fleet → Agents. The page header reads Agents with the subtitle Monitor fleet health, manage scanner modules, and track network coverage. The top-right corner carries the New Token button.
The fleet metrics strip
The strip across the top of the page is a six-tile summary of the whole fleet. Read it left to right:
| Tile | What it means |
|---|---|
| Nodes | Total active agents in the workspace. The small Nw and Nd annotations underneath split that count between Windows and Docker. |
| Online | Agents that reported a heartbeat in the last 20 minutes. The green pulsing dot is your "all good" signal. |
| Outdated | Agents running an older build than the latest published release for their runtime. Windows and Docker are compared against separate manifests, so a Docker agent is never flagged "outdated" because a new Windows MSI shipped. |
| Offline | Agents that registered at least once but haven't sent a heartbeat in 20 minutes. |
| Pending | Tokens you generated where the agent hasn't completed its first connection yet. These have never registered. |
| Coverage | Online ÷ Nodes, rendered as a percentage. The number a CISO will look at first. |
Above the strip you'll also see one or two release banners when a release manifest is published. The lime banner is the latest Windows MSI (with the SHA-256 fingerprint and a download button). The blue banner is the latest Docker image (with the digest and image reference). The CLI button on the Windows banner toggles a copy-pasteable msiexec command for unattended installs.
The agents list
Each agent is a row in the list. The row at a glance:
- Identity icon with a coloured status dot at the bottom-right. Green for online, amber for offline, grey for pending. The icon is the Windows logo for MSI agents and the Docker whale for container agents.
- Hostname (or the agent name if the host hasn't checked in yet) followed by a status pill: Online, Offline, or Pending. An amber pulsing Update pill appears next to the hostname when the agent is running an older build.
- OS line:
Windows Server [version]orDistroless container, followed by the running build (v[N.N.N]) and an arrow to the latest available build when an update is available. - Last seen: a relative timestamp on the right, rendered in your workspace timezone. A pending agent shows Never connected in amber instead.
- Tags: the site badge (if the agent is assigned to a site) and per-module pills. Self-Scan in violet means the agent scans its own host. FG ·
[count]in orange means the agent is acting as a FortiGate proxy for[count]device(s).
Click a row to slide open the agent detail panel on the right. Click the same row again to close it.
The agent detail panel
The detail panel has three tabs across the top. The action buttons at the very top of the panel only render when the agent is Online, because they queue commands the agent picks up on its next heartbeat and there's no point queuing them for a dead agent.
Overview tab
The first card shows connectivity at a glance with one of three lines:
- Actively reporting with the last heartbeat shown as a relative timestamp.
- Awaiting first connection for tokens that have never been used.
- Not responding for agents that missed the 20-minute window. A small RSA badge on the right confirms the agent has completed its key handshake.
Below that, the System card shows the agent's identity. For Windows agents you'll see hostname, OS version, build, and (once the agent has reported under the current protocol) the Active Directory domain it sits in, its domain role (Domain Controller, Member Server, Workstation, or Standalone), and the timestamp of the last scan in each module (Last Retrievy scan, Last GPO scan, Last FortiGate scan). Docker agents show the container ID, the runtime label, the image reference, the build, and the latest available version.
The Scanning Modules card carries the toggles that turn capabilities on and off for this agent:
- Windows OS Hardening (Windows only). Scans the host itself against Retrievy's hardening rules. On a non-Domain-Controller host this toggle is locked off with the hint Available on Domain Controllers only. This host can proxy FortiGate scans.
- FortiGate Network Proxy. Lets this agent reach FortiGate firewalls on your network and ship their config back to Retrievy. When on, the line underneath shows how many devices are currently assigned through this agent.
Assigned Assets tab
This is the inventory of what the agent actually scans. If self-scan is on, you'll see the Windows host listed under a Windows Host card (violet). If the FortiGate proxy is on, you'll see each assigned firewall listed under FortiGate Proxy Targets (orange) with host, port, and optional VDOM. The View link on each firewall row jumps to its full configuration page.
A blank state here with No assets assigned means you have an agent enrolled with no modules enabled and no FortiGate devices pointing at it. Flip the toggles in Overview to fix that.
Security & Auth tab
This is the security forensics view. Four cards:
- RSA-4096 Identity Key. Green when the agent has handed over its public key. Amber No key registered yet until the agent's first boot completes the key handshake. FortiGate API tokens are encrypted with this key and decryptable only inside the agent.
- Token Lifecycle. Four rows: Install Token (consumed or still pending registration), Session Token (active and hashed, not issued yet, or cleared), Revoked At (timestamp or Not revoked), and Registered (creation timestamp).
- Pending Commands. Only appears when commands are queued (a forced scan or update check the agent hasn't picked up yet). Each command shows as a small amber chip.
- Danger Zone. The Revoke Agent button lives here. See Revoking an agent below before clicking it.
Per-agent actions
Run Scan
The lime Run Scan button at the top of the detail panel queues a scan command for an online agent. The toast confirms Scan queued for [hostname]. Starts on next heartbeat. The agent picks it up within ten minutes (the default heartbeat cadence) and starts work immediately. Trying to Run Scan on an offline agent shows Agent is not online and does nothing.
Update
The sky-blue Update button only appears when this agent is older than the latest published release for its runtime. It queues an update check command. On a Windows agent the host pulls the new MSI on its next heartbeat and reinstalls itself. On a Docker host with the optional Watchtower companion running, the new image is pulled automatically and the container restarts.
Generate a new install token
To enrol another agent, click New Token in the top-right of the page. The modal asks for an Agent Name (something descriptive like dc01-london or fortigate-scanner-eu) and a Runtime (Windows Agent or Docker Agent). After Generate Token, the next screen shows the token once and counts down the 60-minute expiry. Copy it before you close. If you miss the window, generate another one.
The token reveal screen also renders the install command for the runtime you picked: an msiexec line for Windows, two docker run lines for Docker (the agent plus the optional auto-update companion). See the Windows install guide or the Docker install guide for what to do with the token on the host side.
Revoking an agent
Open the agent's Security & Auth tab and click Revoke Agent at the bottom. A confirmation modal opens with a five-second cooldown on the Confirm Revocation button so a stray click can't kill an agent.
Revoking is not a pause. The agent permanently uninstalls itself on its next contact with Retrievy. On Windows the service unregisters, the binaries under C:\Program Files\Retrievy are deleted, the offline scan queue is wiped, and the DPAPI-protected RSA keys are destroyed. On Docker the container wipes its state volume and exits. To bring the host back online you install a fresh agent with a new install token.
If the agent is currently proxying for one or more FortiGate firewalls, the modal shows an amber Proxy Connection Alert with the device count. Revoking clears those FortiGate devices' agent assignment (they fall back to No agent assigned) and you'll need to Edit each FortiGate device and re-enter its password after re-enrolling, because Retrievy never stores the plaintext password and the agent-side decryption key is destroyed on revoke.
Heartbeat and status alerts
Each agent posts a heartbeat to Retrievy on a ten-minute cadence. The page uses a 20-minute window to decide whether an agent is Online or Offline, so a single missed heartbeat keeps the agent green and only a second missed beat flips the badge.
Background monitoring runs every five minutes and emails users with the Manage Agents permission according to this schedule:
| Trigger | What you get |
|---|---|
| Agent has been offline for more than 1 hour and you haven't been alerted yet | A first Agent offline email naming the hostname and the last-seen timestamp. |
| Agent stays offline, 24 hours since the last email | A daily roll-up email with the total time offline so far. |
| Agent comes back online after a flagged outage | A back online all-clear email with the restoration time and total downtime. |
Agents that have never registered (still Pending) don't trigger alerts. Revoked agents are excluded entirely.
Auto-update
Each agent compares its build against the latest release manifest for its own runtime on every heartbeat. The two manifests are independent: publishing a new Windows MSI doesn't flag Docker agents as outdated and vice versa.
When a Windows agent sees a newer MSI on the manifest, it pulls it and reinstalls itself silently. The service restarts under LocalSystem with no operator action required. Docker agents update through the optional Watchtower companion container shown on the token reveal screen: Watchtower watches the registry, pulls new digests, and swaps the container in place. Hosts that don't run Watchtower stay pinned to whatever digest they were started with, which is the right behaviour for change-controlled environments.
The amber Update pill on a row and the Update action button in the detail panel both read from the same per-runtime comparison, so the list view and the action view never disagree.
Sites and tags
A site is a colour-coded grouping you can attach to an agent (think London office, Frankfurt DR site, Lab). When an agent has a site, the site chip appears on the row, in the detail panel header, and as a row in the System card. The chip carries the site's colour so a fleet view across many regions is easy to scan.
Sites are configured outside this page. Open the Sites settings to create one, then assign it to an agent from there.
How this affects your Retrievy Index
The Agents page itself doesn't move your Retrievy Index. What lives here is the plumbing: which agents are talking to Retrievy, which modules they're allowed to run, and how recently they reported. The score work happens when the agent ships findings, not when you look at the list.
There's one operational consequence worth understanding. An Offline agent stops feeding findings into its modules. The score doesn't fall on its own when an agent goes quiet, but the module that depends on it will get progressively staler. A long outage on the agent that scans your Active Directory means the ISPM and SCM views for that domain stop reflecting reality, and the Retrievy Index keeps reporting yesterday's posture. Treat a sustained Offline state as a freshness incident, not a scoring incident, and re-enrol or replace the agent before the next regulator review.
For the underlying math (per-module weights, severity coefficients, the asymptotic curve), see the Retrievy Index.
Troubleshooting
Symptom: An agent sat on Online yesterday and now reads Offline.
Fix: Confirm the host is up and outbound HTTPS to your workspace still works. Windows: check the Retrievy Agent service status with Get-Service RetrievyAgent. Docker: docker ps --filter name=retrievy-agent. If the service is running but the agent is still Offline, restart it. If a corporate proxy or firewall change blocked the workspace URL, the agent's local log will show the connection error.
Symptom: Status reads Pending with Never connected in amber hours after generating the install token.
Fix: The install token is one-time-use and expires 60 minutes after generation. If the agent didn't complete its first connection before that, the token is dead. Generate a new token and reinstall (or rerun the docker run line) with the new value.
Symptom: An Update pill won't clear after you forced an update. Fix: The update command queues for the next heartbeat. Give the agent up to ten minutes. If it still reads outdated, open the detail panel and watch the Pending Commands card on the Security & Auth tab. A stuck command there means the agent picked up the command but the install hasn't completed. Check the agent's local log on the host.
Symptom: Run Scan runs but no findings appear in the relevant module dashboard. Fix: First, confirm the scan completed: the Last Retrievy scan / Last GPO scan / Last FortiGate scan rows on the Overview tab will update to a recent relative time. If the timestamp moved but the dashboard didn't, the issue is downstream of the agent (the upload is processed by Retrievy and rebuilds the module view on the next cycle). If the timestamp didn't move, the scan failed on the host. Open the host's local log for the error.
Symptom: The Windows OS Hardening toggle is locked and won't turn on. Fix: The agent has reported its role as Member Server, Workstation, or Standalone. Windows OS Hardening is supported only on Domain Controllers. The host can still act as a FortiGate proxy. If the host really is a DC and the role is wrong, restart the agent so it re-reports.
Symptom: Revoke Agent completed but the host is still listed. Fix: Revoked agents drop off the active list on the next page render. If you still see the row, refresh the page. If the host hasn't completed its self-destruct yet (because it was offline at the moment you revoked), it will self-destruct as soon as it next reaches Retrievy: an HTTP 410 on its first heartbeat tells it to uninstall.