Inventory

The Hermes agent discovers hardware, software and configuration on each Windows and Linux endpoint and reports it to the server. Inventory is organized into modules. The agent keeps its own copy of the last collection and, after the first report, sends a module again only when its content has changed.

What's collected#

Each module covers one area of the endpoint. Not every module exists on both platforms. The linked pages describe what each area shows on the agent details page.

How inventory reaches the server#

Collecting inventory and sending it are separate steps. The agent collects into a local copy on the endpoint. It then sends the server only the modules that the server doesn't already have in their current form.

1. On connect. When the agent connects to a server, it sends its stored inventory right away and doesn't collect again first. On a fresh install with nothing stored yet, it runs a full collection first and then sends the result.
2. Periodic full collection. Every Full Inventory Interval (see Refresh intervals) the agent collects every module again and updates its local copy. This step on its own sends nothing to the server.
3. Changes only. At the heartbeat cadence, the agent compares each stored module with what it last sent to each connected server. It sends a module only if the module has changed. A changed module is sent in full. An endpoint where nothing changed sends no inventory traffic between collections.
4. Metrics are not part of this comparison. They travel with every heartbeat.

Commands have priority over inventory. If a command is running when a periodic collection is due, the agent skips that collection and tries again at the next interval. If a command starts during a collection, the agent stops collecting for that pass.

An agent that reports to more than one server (see Multi-Homed Agents) collects once and tracks what it has sent to each server separately. Each time a server connection is re-established, the agent sends that server its full stored inventory again.

Agent properties derived from inventory#

As modules arrive, the server updates a few properties on the agent record. You can use these properties in filters and dynamic collections:

Querying inventory#

GET api/agents/{agentId}/inventory returns everything the server holds for an agent. Sub-routes return a single area:

Areas without their own sub-route, such as shares, local groups or environment variables, are included in the full GET api/agents/{agentId}/inventory response. All of these routes need the inventory.view permission, which the built-in Helpdesk, Operator and Admin roles include (see Permission Model). They return 404 when the agent doesn't exist or hasn't reported that area yet, and 403 without the permission.

These routes return what the server already holds. To make an agent collect fresh data first, use Collect inventory now. Fetch the hardware inventory for an agent over the API:

# Fetch hardware inventory for one agent
$headers = @{ Authorization = "Bearer $token" }

Invoke-RestMethod `
  -Uri "https://athena.example.com:8443/api/agents/$agentId/inventory/hardware" `
  -Headers $headers `
  -SkipCertificateCheck

Collect inventory now#

Agents report inventory on their own schedule. When you need current data right away, for example after installing software, changing hardware or fixing a configuration, use Collect inventory. The agent runs a fresh, full collection of every module. It does not resend the snapshot it already has. This works on both Windows and Linux agents.

Where to start it

The Agents list clears your selection when you change page, filter or search, so Athena never acts on agents you can no longer see. The same selection also drives Restart.

Who can use it

Collecting inventory requires the agents.manage permission. The built-in Operator and Admin roles include it (see Permission Model). Users without it do not see the button, the Agents-list checkboxes or the collection button. The REST API returns 403 to them.

What you see

Athena sends the request to each agent that is connected right now. Nothing is queued for offline agents, so run the request again once they are back online. Every targeted agent gets one of these outcomes:

• Single agent: a toast reads Inventory requested - the page updates as the agent reports, Agent is offline - inventory was not requested, or Could not send the inventory request to the agent.
• Agents list or collection: a toast reads Inventory requested from x of y agents (z offline). If no agent received the request, it is shown as a warning.
• On the agent details page, the Last Inventory card (Most recent module received) and the inventory sections update live as each module arrives. You don't need to reload the page.

REST API

Both return the totals totalRequested, sentCount, offlineCount and failedCount (failed plus not found), and a results array of { agentId, hostname, status }. The inventory itself arrives asynchronously. Read it afterwards with the inventory routes.

# Collect fresh inventory from every member of a collection
$headers = @{ Authorization = "Bearer $token" }
$body = @{ collectionId = $collectionId } | ConvertTo-Json

$r = Invoke-RestMethod -Method Post `
  -Uri "https://athena.example.com:8443/api/agents/inventory/refresh" `
  -Headers $headers -ContentType "application/json" -Body $body `
  -SkipCertificateCheck

$r.data.results | Where-Object status -ne "Sent"   # who still needs a retry

Auditing

Each request writes one InventoryRefreshRequested event to the audit log. It records who asked and lists the hostnames that were sent the request, offline, failed or not found. The action is CollectInventory, or UpdateScan when the collection came from Scan for Missing Updates.

Refresh intervals#

Two fleet-wide settings control how fresh inventory is. You set both on Settings → Agents (see Agent Settings, which also lists their defaults). The server pushes changes to connected agents.