Agent Data Folder Layout
Every Hermes agent keeps its certificates, local state, queued results, deployment working files and
downloaded updates in one data folder. Current agents organise that folder into a small
set of top-level folders: servers, state, outbox, work
and downloads, with logs in Logs. Agents installed before this layout
move their folder automatically, once, after an update. This page lists where everything
lives on Windows, Linux and macOS, how the move works, and what to change in your antivirus exclusions
and scripts.
The layout ships in two agent releases per platform. The first reads both layouts but never moves anything: Windows 1.2.164, Linux 1.2.142, macOS 1.2.149. The next one moves the folder: Windows 1.2.165, Linux 1.2.143, macOS 1.2.150. Agents pick both up through a normal agent update; nothing has to be reinstalled.
Where the data folder is#
| Platform | Data folder | Agent logs |
|---|---|---|
| Windows | C:\ProgramData\Hermes | C:\ProgramData\Hermes\Logs |
| Linux | /var/lib/hermes | /var/lib/hermes/logs |
| macOS | /Library/Application Support/Hermes | /Library/Logs/Hermes |
If Agent:DataPath is set in the agent's configuration
file, that folder is the data folder instead. With the new layout, Agent:DataPath also
holds the agent's local state databases, which older agents always kept in the default folder.
What is in it#
The layout is the same on every platform. Paths below are relative to the data folder; on Linux and macOS
use / instead of \.
| Folder | What it holds |
|---|---|
servers\<name>\ | One folder per Athena server the agent reports to (primary for a normal install): the agent certificate and key (agent.pfx), the pinned server CA (ca.crt), the registration state (server-state.json) and the scan definitions it received. Unchanged from older agents. |
state\ | The agent's local databases (inventory-state.db, compliance-state.db, assignment-state.db, monitor-state.db) and local-actions.json. |
state\modules\<module>\ | Per-module files: the last policy received (policy.json), what the device last reported (reported.json), the module's own state (state.json), and for Sysmon the enforced files (files\). |
outbox\ | Results waiting to be sent to the server: compliance evaluations (evaluations.db), local actions (local-actions\) and tamper reports (tamper\). |
work\deployments\ | One folder per package deployment run, deleted when the run ends unless a step keeps it. |
work\scripts\, work\commands\ | Temporary script files, and the working directory of commands run without one. |
work\module-files\ | Files delivered by policy modules. |
downloads\agent\ | Agent self-update: the downloaded build (pending\), the backup of the previous build (backup\, newest only) and the update status files. |
downloads\helper\pending\ | Downloaded Remote Helper builds. |
Logs\ (logs/ on Linux) | The daily agent log (hermes-*.log) and, under servers\<name>\, each server's connection-*.log. On macOS this is /Library/Logs/Hermes. |
layout.json | Records which layout the folder uses. Do not edit or delete it. |
A few files stay at the top of the data folder, among them layout.json and
wsusscn2.cab (offline Windows Update scanning). On
macOS the agent program and its appsettings.json also live there.
Old and new locations#
Use this table to update scripts, monitoring, or backup jobs that point at the old paths (Windows names; Linux names in brackets where they differ).
| Before the move | After the move |
|---|---|
inventory-state.db, compliance-state.db, assignment-state.db, monitor-state.db, local-actions.json (top level) | state\ |
policies\<module>.json | state\modules\<module>\policy.json |
device-state\<module>.json | state\modules\<module>\reported.json |
restart-state.json, shortcuts\manifest.json | state\modules\restart\state.json, state\modules\shortcuts\state.json |
ModuleFiles\sysmon-enforce\ | state\modules\sysmon\files\ |
Other ModuleFiles\ folders | work\module-files\ |
evaluation-outbox.db, local-action-outbox\, tamper-outbox\ | outbox\evaluations.db, outbox\local-actions\, outbox\tamper\ |
Deployments\ (deployments/) | work\deployments\ (see kept deployment folders) |
TempScripts\ (scripts/) | work\scripts\ |
WorkingDirectory\ (Linux, macOS: the data folder itself) | work\commands\ |
updates\ (update/) | downloads\agent\ |
helper\pending\ | downloads\helper\pending\ |
servers\<name>\connection-*.log | Logs\servers\<name>\connection-*.log |
How the move happens#
You do not run anything. After an agent is updated to the moving release:
- The new build first has to prove itself the normal way: it passes its self-test, connects to the server and outlives the updater's health check, so the update can no longer roll back. Until then it keeps using the old layout.
- The agent then restarts itself once. On Windows it restarts the
HermesAgentservice a few seconds later; on Linux and macOS it exits and systemd or launchd starts it again. - On that start, before it opens any file, the agent moves the folder and writes
layout.json. It then re-applies the data-folder lock-down to the moved folders (on Windows, access for SYSTEM and Administrators only; see Agent Tamper Protection).
A fresh install that has no earlier state uses the new layout straight away. Expect the agent to show offline for a moment during the one extra restart.
Safe if interrupted#
- Every step is a rename within the same disk. If power is lost or the service is killed mid-move, the next start finishes the move before the agent does anything else.
- Nothing is overwritten or deleted. If a file already exists at the new location, the new copy wins and the old file is left where it was (the agent logs it).
- Links (junctions, symlinks) inside the data folder are never followed; they are left in place.
- Certificates under
servers\are not moved, so the agent keeps its identity on every server.
What the agent log shows#
Look for these lines in the agent log:
| Message | Meaning |
|---|---|
| "Data folder: this build is committed and still on layout 1 - restarting … once to move it to layout 2" | The one-time restart is starting. |
| "Data folder <path>: moving to layout 2" | The move is starting. |
| "Data folder <path>: resuming the interrupted layout move" | An earlier move was cut off; it is being finished. |
| "Layout move: <path> is layout 2 (N moved, M left in place)" | The move finished. M counts items left in place because of a conflict or a link. |
| "Layout move: <new> already exists; <old> left in place" | A conflict; the old item can be inspected and removed by hand. |
| "Layout move stopped after N step(s), resumes on the next start: …" | An error stopped the move (for example a file locked by another program). The next start of the agent finishes it. |
| "Data folder <path>: layout 1" or "layout 2" | Logged at every start: the layout in use. |
Kept deployment folders & antivirus exclusions#
Deployment folders left behind under the old Deployments\ folder (a step set to skip cleanup,
or a run that crashed) are not moved. New runs go to work\deployments\. On
Windows, the Cache tab of the Agent Control Panel applet
lists folders from both places, and deleting debug files clears both and removes the old
Deployments\ folder once it is empty.
If your antivirus excludes C:\ProgramData\Hermes\Deployments, add
C:\ProgramData\Hermes\work\deployments before the moving release reaches your fleet.
Otherwise package installs that the exclusion used to cover will be scanned again. Review any other
exclusion or monitoring rule that names an old path from the table above.
Rolling back agents after the move#
An agent older than the reading release cannot read a moved folder. So Athena refuses to push an agent that runs the moving release (or newer) to a version below the reading release, even with force:
| Platform | Agents at or above | Oldest version you can push |
|---|---|---|
| Windows | 1.2.165 | 1.2.164 |
| Linux | 1.2.143 | 1.2.142 |
| macOS | 1.2.150 | 1.2.149 |
A refused push appears in the agent's update history as Failed with the reason
"Refused: agent <version> uses the layout-2 data folder, which <target> cannot read. The
oldest <platform> agent it may be pushed or rolled back to is <version>.", and is recorded
in the audit log as AgentUpdatePushFailed (see Audit Event
Types). An update that rolls back on its own before the move is safe: the move only happens after the
new build is committed.
Update clean-up#
From the reading release onward, the agent tidies its update folder:
- When an update is committed, the update status files from the attempt are removed and, on Windows, only the newest backup of the previous agent build is kept.
- At start-up, unfinished download files (
*.tmp) older than one day are deleted from the agent update download folder (on Windows, also the Remote Helper download folder). Each deletion is logged as "Deleted stale transfer file …".
Certificates under servers\, the state databases, logs and kept deployment folders are never
touched by this clean-up.
Related#
- Agent Binaries & Updates: pushing, rolling back and update history.
- Agent Logs: reading the agent log on the machine and from the console.
- Agent Configuration File:
Agent:DataPath. - Agent Control Panel Applet: the Cache tab.
- Multi-Homed Agents: the per-server folders.
- Agent Tamper Protection: the data-folder lock-down and uninstall.