Agents (Fleet View)
The Agents screen is your fleet roster — one row per enrolled machine, with its status, operating system, address, versions, and tags at a glance. It's where you find a specific host, gauge how much of the estate is reachable, and open an individual agent to act on it. This page explains what the list shows, how status is decided, how to filter and search the fleet, and how to pull the same list and roll‑up counts over the REST API or with the Athena PowerShell module.
Viewing the fleet requires the Helpdesk role or above. Renaming an agent or changing its tags requires Operator or Admin, and permanently deleting an agent requires Admin. See Roles & Permissions for the full matrix.
Agent status#
Every agent carries a status that reflects its current relationship with the server. The list colour‑codes each row by status so you can spot unreachable machines quickly.
| Status | What it means |
|---|---|
| Pending | The host has registered but is awaiting approval — it is not yet an active member of the fleet. |
| Online | The agent is registered and connected, sending heartbeats on schedule. |
| Offline | The agent is registered but has stopped checking in (missed heartbeats). |
| Busy | The agent is connected and currently running a task (for example a command or deployment step). |
| Revoked | The agent's registration has been revoked; its certificate is no longer trusted and it can no longer connect. |
| Error | The agent reported an error condition that needs attention. |
An agent is considered to have a stale heartbeat when its last heartbeat is more than 5 minutes old. This is the signal the server uses to move an agent toward Offline once it stops checking in — a machine that was powered off or lost its network path will show a stale last‑heartbeat time before it settles as Offline. You can tune how often agents check in from Agent Settings.
What the list shows#
Each agent record carries the identifying and health fields below. The same values are returned by the API and PowerShell, so you can build your own views and exports from them.
| Field | Description |
|---|---|
| Hostname | The machine's hostname as reported at enrolment. |
| Display name | An optional friendly name you can set for the agent; it can differ from the hostname. |
| IP address | The agent's last‑seen address. |
| Operating system | Windows, Linux, macOS, or Unknown, plus the OS version string. |
| Agent version | The version of the Athena agent software running on the host. |
| Status | Current status (see Agent status). |
| Last heartbeat | When the agent last checked in. |
| Last inventory | When the agent last reported inventory. A record is treated as having recent inventory when it is under 24 hours old. |
| Registered | When the agent first enrolled. |
| Certificate expiry | When the agent's certificate expires. The record flags a certificate that is already expired, or expiring within 30 days, so you can renew ahead of time — see Certificates & PKI. |
| Tags | The agent's tags, used for grouping and targeting. |
| Classification | Derived flags from inventory — for example server vs. desktop OS, domain controller, domain‑joined (with domain name), virtual machine, and chassis type (laptop, tablet, small form factor). |
| Uptime | Derived from the host's last boot time. |
| Maintenance | Whether the agent is in maintenance mode (and, if so, the reason, who enabled it, and any scheduled end time). |
| Unattended | Whether the agent is designated for unattended remote access. |
Filtering & search#
The fleet is paginated and filterable so it stays workable at scale. You can narrow the list by status, operating system, or a free‑text search on hostname/display name, and page through the results.
| Filter | Accepted values |
|---|---|
| Status | Online, Offline, Pending, Maintenance |
| Operating system | Windows, Linux, MacOS, Unknown |
| Search | Any text; matches on hostname or display name |
| Tag | Return every agent carrying a specific tag |
Results come back a page at a time (20 agents per page by default). Filters combine, so you can list, say, only online Windows machines matching web.
Opening an agent#
Selecting a row opens that agent's detail view, the jumping‑off point for everything you can do to a single machine:
- Review its inventory — OS, hardware, processors, memory, storage, network, installed software, services, features, and Windows updates.
- Rename it or edit its tags and metadata.
- Run remote commands or start a remote desktop session.
- Put it into (or take it out of) maintenance mode.
- Toggle unattended access or its screen‑share recording policy.
- Revoke or retire the agent when it leaves service.
Fleet stats#
Athena also exposes roll‑up counts for the whole fleet, the same figures used for at‑a‑glance monitoring on the Dashboard:
| Count | Description |
|---|---|
| Total | Every agent in the system. |
| Online | Agents currently connected. |
| Offline | Agents that have stopped checking in. |
| Maintenance | Agents currently in maintenance mode. |
| Warning | Agents needing attention — for example a certificate that is expiring soon. |
Query the fleet over the API#
The Agents endpoints return the same records and counts as the screen. Listing and reading agents requires a Helpdesk (or higher) token; see the API Reference for authentication.
# List agents, filtered and paginated
GET /api/agents?page=1&pageSize=20&status=Online&os=Windows&search=web
# A single agent by ID, or by hostname
GET /api/agents/550e8400-e29b-41d4-a716-446655440000
GET /api/agents/hostname/SERVER01
# Every agent carrying a tag
GET /api/agents/tags/production
# Fleet roll-up counts
GET /api/agents/stats| Query parameter | Description |
|---|---|
page | 1‑based page number. Default 1. |
pageSize | Items per page. Default 20. |
status | Online, Offline, Pending, or Maintenance. |
os | Windows, Linux, MacOS, or Unknown. |
search | Text matched against hostname or display name. |
PowerShell#
The Athena PowerShell module wraps the same endpoints. Get-AthenaAgent lists and
filters the fleet; Get-AthenaAgentStats returns the roll‑up counts. Both require a
Helpdesk role or higher.
# First page of agents (20 by default)
Get-AthenaAgent
# Filter by status, OS, or search term
Get-AthenaAgent -Status Online
Get-AthenaAgent -OS Linux
Get-AthenaAgent -Search "web"
# Look up one agent by hostname, or by tag
Get-AthenaAgent -Hostname "SERVER01"
Get-AthenaAgent -Tag "production"
# Page through, or pull everything and export
Get-AthenaAgent -Page 2 -PageSize 50
Get-AthenaAgent -All | Export-Csv agents.csv -NoTypeInformation
# Fleet counts (Total / Online / Offline / Maintenance / Warning)
Get-AthenaAgentStats
(Get-AthenaAgentStats).Online
Get-AthenaAgent accepts -Page (from 1) and -PageSize
(1–100, default 20), and -All retrieves every page — use it with care on a
large estate. Because Get-AthenaAgent emits agent objects, you can pipe them
straight into other cmdlets, for example:
# Put every production agent into maintenance mode
Get-AthenaAgent -Tag "production" | Enable-AthenaAgentMaintenance
# Rename an agent found by hostname (Operator or Admin)
Get-AthenaAgent -Hostname "SERVER01" | Set-AthenaAgent -DisplayName "Prod Web 01"Agent Enrollment to add machines · Agent Tags for grouping · Inventory for per‑agent detail · Maintenance Mode · Retiring & Removing Agents · Roles & Permissions.