Agents

The Agents page is the main device list. Each entry shows an online/offline indicator, hostname, OS/architecture, and how long ago the device last checked in. The header shows a live count of online, offline, and total agents.

Finding a device

Use the search box to filter by hostname, agent ID, or a custom label, or narrow the list with the platform dropdown when your fleet spans multiple operating systems. The All / Online / Offline buttons narrow the list by state. Links from the Overview (for example the red Offline tile) and from the search palette open this screen with that filter already applied, and the filter is part of the page address (/app/agents?status=offline) so you can bookmark it.

Device detail

Selecting a device opens its detail panel with four tabs:

• Overview — current CPU and memory usage with core count, per-disk usage bars, the device’s department, and a collapsible table of recent telemetry.
• CPU / Memory / Disk — a 24-hour usage chart for the metric, with average and peak shown below the graph.
• Compliance — the device’s compliance score, pass/warn/fail counts, and the result of each rule.

You can give a device a friendly label (for example, “Lab Room 3 – PC 12”) by clicking the label next to its hostname.

How the agent protects busy machines

The agent reports a health pulse every 10 seconds. If the machine it runs on is under sustained load — average CPU at or above 85%, or memory at or above 92%, for about 30 seconds — the agent slows its pulse to every 30 seconds so it never competes with your workload. It returns to 10 seconds after roughly three minutes of calm. A single spike does not trigger this, and the agent never samples faster than 10 seconds. While backed off, charts for that machine have fewer points; nothing is lost beyond the sampling gap.

Investigation Mode

When you are diagnosing a problem on one machine, open it in Agents and click Investigate (10 min) (Technician or above, machine must be online). That agent samples every 2 seconds instead of every 10 for the chosen time, then returns to normal by itself — you never have to remember to turn it off. It can run for at most 15 minutes. If the machine itself is under heavy load, the agent keeps a floor of 5 seconds so monitoring never makes the problem worse. The request is recorded in the Audit Log and Pending Actions history like any other agent action.

Investigation Mode changes only how often the agent reports its normal health data. It does not collect anything extra (it does not read files, capture screens or open network connections), and deeper diagnostics are separate features.

The agent looks after the machine too

The agent lengthens its reporting interval on its own, and returns to the normal 10 seconds when the reason passes:

• Heavy load. CPU at or above 85%, memory at or above 92%, or the busiest disk busy at least 90% of the time, for about 30 seconds in a row, moves it to every 30 seconds. It needs about three minutes of calm to go back.
• On battery. A laptop running on its battery reports every 30 seconds, and every 60 seconds when the charge is 20% or lower. Plugging in restores the normal interval after a moment. A machine with no battery, or whose charge level cannot be read, is never treated as being on battery.

Disk activity is measured on Windows and Linux. macOS reports battery state but not disk load. The interval only ever gets longer than normal, never shorter, and Investigation Mode still works on a laptop. To keep the fixed 10-second interval on a machine, set the environment variable GUARDIAN_GOVERNOR=off for the agent service.

Agent health and stopped agents

Guardian tells you when a monitoring agent stops, and when an agent misbehaves, so a quiet machine never goes unnoticed. Each device’s detail page has an Agent health panel, and the same events raise alerts and in-app notifications with a recommended action.

When an agent stops

The agent records how it ended, so the hub can tell the difference between:

What happened	Alert	Severity
The process was ended without warning (Task Manager, kill -9, the out-of-memory killer, a crash) and the service manager started it again	Agent Stopped Unexpectedly	Warning
The same thing three or more times in an hour	Agent Keeps Stopping	Critical
Someone stopped the service on purpose (Services, systemctl stop)	Agent Service Was Stopped	Warning, clears when the agent runs again
The machine was shut down or restarted	No alert; the device simply reports again when it is back	Info
An install, upgrade or uninstall stopped it	No alert; these announce themselves first	None

The service settings restart a killed agent within seconds on Windows, Linux and macOS, so monitoring resumes by itself and the alert tells you it happened. If an agent goes silent and never announced a stop, the Agent Offline alert now says which of these is most likely (power or network loss, or an ended process) and what to check.

When an agent uses more than it should

The agent measures its own memory, CPU and internal tasks and reports them every five minutes. It normally uses well under 100 MB and a few percent of one core. You are alerted when, for three checks in a row:

• More memory than expected at 300 MB, or too much at 800 MB.
• More CPU than expected at 10% of one core, or too much at 30%.
• Too many internal tasks (3,000 or more).
• Memory keeps growing: it has doubled over eight checks without ever shrinking, which suggests a leak.

The agent also protects the machine itself. If it passes a soft memory limit it frees memory; if it passes the hard limit it restarts itself cleanly and reports Agent Restarted Itself (Memory). The limits can be tuned for the agent service with the environment variables GUARDIAN_AGENT_MEM_SOFT_MB and GUARDIAN_AGENT_MEM_LIMIT_MB.

Every one of these alerts carries a recommended action. For a misbehaving agent the first is usually Restart agent (Technician or above, device online), described under Remediation.

Department assignment

Superadmins can reassign a device to a different group directly from the Overview tab — pick the new department from the dropdown and it takes effect immediately. Other roles see the device’s current department as a read-only badge.

Device identity, ownership and lifecycle

The Device identity panel is collapsed to one summary line (ownership, environment, release channel and a short Device ID) so the device’s live numbers stay on screen. Click Manage to open it. Warnings are never hidden by the collapse: a suspected clone and a device that is not reporting normally always show, and a revoked or retired device opens the panel by itself so Restore is one click away. Each device has two separate identities:

• Device ID — a stable ID Guardian assigns once. It does not come from the hostname or hardware and does not change when the machine is renamed, reinstalled or its credentials are replaced.
• Agent ID — identifies one installed copy of the agent and the credentials it uses to report.

Ownership records how the machine is used: Dedicated (one person), Shared (lab, front desk), Kiosk, Infrastructure (server or appliance) or Unassigned. Only a dedicated device can have an assigned user. Shared, kiosk and infrastructure machines are used by many people or none, so a stored owner would quickly be wrong. You can also record an environment (for example “production”). The ownership, environment and release channel (Stable, Early access or Canary) of newly enrolled devices come from the enrollment token used to install them, not from the machine.

The panel also shows the device’s health, worked out from what Guardian actually knows:

• Healthy — connected and reported within the last 90 seconds. A machine that is busy and has slowed its reporting to every 30 seconds still counts as healthy.
• Delayed — still marked connected, but nothing heard for between 90 seconds and 5 minutes. It may be overloaded or about to disconnect.
• Offline — not connected, or marked connected but silent for over 5 minutes.
• Revoked or Retired — set by an administrator, and shown instead of the above.

Superadmins can change a device’s lifecycle state from the same panel:

• Revoke — for a lost, stolen or compromised machine. Its credentials are deleted at once and it stops reporting. It cannot enroll again, even with a valid token, until an administrator restores it. History is kept.
• Retire — for a decommissioned machine. Credentials are deleted and history is kept. Installing the agent on it again re-activates it.
• Restore / Reactivate — allows a revoked or retired device to enroll again. This asks you to re-authenticate. The old credentials stay deleted, so the agent must be installed or re-enrolled with a valid token to start reporting.

Every change is recorded in the Audit Log.

Revoking or retiring a device also closes its live connection straight away, so it stops reporting at once rather than at its next reconnect.

Who is signed in

The device header shows Signed in: name for the person signed in at the machine’s own screen right now, as reported by the agent every few seconds (on Windows DOMAIN ame). This is separate from assigned user, which is who the device belongs to: a shared or kiosk machine has one assignment and many people signing in over a day. An offline device shows Last signed in. Nothing is shown for an agent that has not reported it (older agents, or a platform that cannot tell), and remote sessions (SSH, a second Remote Desktop user) are not counted. Because a username is personal data, it is kept only as the latest value on the device record; Guardian does not keep a history of sign-ins.

Notifications

Guardian tells your team in the app (the bell) when something happens to a device that they did not necessarily do themselves: a device was revoked, retired or restored (with who did it and why), the Guardian platform team revoked or retired one of your devices (with the reason they gave), a revoked device tried to enroll again (at most one notice a day per device, however often the machine retries), and a suspected cloned machine.

Cloned machines

If you copy a VM or disk image, the copy has the same identity and credentials as the original, so Guardian cannot tell them apart and their data mixes. When the same device identity is connected from two different addresses at the same time, Guardian shows a warning on the device, records it in the Audit Log (once) and sends your team an in-app notification. It does not block either machine, because a machine that changed address can briefly look the same. To fix it, revoke the device, then reinstall the agent on each copy so each gets its own identity.

Device actions (superadmin only)

The device header shows one status chip (Healthy, Delayed, Offline, Revoked or Retired) and the actions you use most: Locate, Investigate and Update Agent. Everything else is in the More actions menu, with the destructive actions in their own Danger zone section so they are never next to the everyday ones. Press Escape to close the menu without doing anything.

Everyday actions (online devices):

• Locate — see Locate a Device.
• Investigate (10 min) — see Investigation Mode above.
• Update Agent — queues an agent update for the device, to the newest version its release channel allows. It does not push immediately; it must be approved in Pending Actions before the agent downloads and installs it.

In the More actions menu:

• BMC / Redfish credential — available regardless of online status; see Locate a Device for details.
• Force offline (online devices) — marks the device offline; it reconnects automatically on its next heartbeat.

In the Danger zone:

• Deregister (delete all data) — permanently deletes the device and all its data: telemetry history, inventory, process list, group membership and anomalies. This cannot be undone.
• Self-destruct agent (online devices) — wipes the Guardian agent binary, configuration, and services from the remote host. This is irreversible and removes all future access to the device, so it requires confirmation.

Bulk actions

Superadmins can check multiple devices in the list and apply Offline or Deregister to all of them at once.

Moving a device to another organization

There is no one-step transfer, on purpose: a device never changes owner unless its current owner lets go of it.

1. In the old organization, a superadmin Deregisters the device. This permanently deletes it and all of its data, including its inventory, process list, group membership and history, and its credentials stop working.
2. In the new organization, install the agent (or re-enroll it) with a token from that organization. It gets fresh credentials and starts with an empty history.

Until step 1 is done, enrolling the device with another organization’s token is refused (HTTP 409, identity_conflict) and nothing about the existing device changes.