Windows Agent

The Hermes agent runs on Windows as a background service. The built-in bootstrap installer onboards a fresh machine in a single elevated command — it prompts for your server and credentials, downloads the current agent build, and registers the host automatically. This page covers how that installer works, where the service, configuration and logs live, how the agent checks in, and how to troubleshoot or remove it.

Requirements#

• A 64-bit version of Windows. The agent installs and runs as a Windows service and is set to start automatically at boot.
• Administrator rights to install — the installer writes the binary, its configuration, and the service into system directories.
• Outbound network reachability from the host to the Athena server on the API port (default 8443) and the agent gRPC port (default 8444). The agent connects outbound only; no inbound ports are opened on the machine.
• A Windows agent binary must already be uploaded and marked active on the server — the installer downloads the latest active Windows build. See Agent Binaries & Updates.

Windows PowerShell 5.1 (built into Windows) is sufficient; PowerShell 7+ also works. The installer tolerates the server's self-signed certificate for the initial download, and verifies the downloaded binary by SHA-256 before installing it.

Installing the agent#

In the console, open Settings → Agents and stay on the Configuration sub-tab (the default). Scroll down to the Agent Installer card — it is shown only to Admin users — and click Windows. The console downloads the ready-to-run script and reveals a copy-to-clipboard one-liner with your server address already filled in. Run that one-liner in an elevated PowerShell on the target machine:

# Copy the exact command from the Agent Installer card — it looks like:
iex ((New-Object Net.WebClient).DownloadString('https://<server>:8443/api/agent-binaries/install-script/windows'))

Running as Administrator, the installer walks through these steps on its own:

1. Prompts for the server host, API port (default 8443), agent (gRPC) port (default 8444), and your console username and password (the password is masked and never written to the log).
2. Signs in to get a session, then resolves the latest active Windows agent binary.
3. Mints a short-lived (10-minute), single-use registration token labelled with the computer name — so no long-lived secret is left behind.
4. Downloads the binary and verifies its SHA-256 against the server-reported hash before installing; a mismatch (or a missing hash) aborts the install.
5. Installs the binary, writes the agent configuration, registers and starts the HermesAgent Windows service, and confirms it reaches the Running state.

The install is idempotent: re-running it stops and re-points an existing installation rather than creating a duplicate, which makes it safe to use to move a host to a new server. A transcript is written to %TEMP%\athena-install.log; the password is never included in it.

Files & service layout#

A standard bootstrap install lays the agent out in predictable locations:

The Windows service is registered with the service name HermesAgent and the display name Hermes Agent. It is configured to start automatically and to restart on failure, so it comes back after a crash, a reboot, or a fatal connection error without intervention. See Service recovery for exactly when that happens.

Managing the service#

Because the agent is a normal Windows service, you manage it with the tools you already use. Run these in an elevated PowerShell (or use services.msc):

# Status, start, stop, restart
Get-Service HermesAgent
Start-Service HermesAgent
Stop-Service HermesAgent
Restart-Service HermesAgent

# Or with sc.exe
sc.exe query HermesAgent
sc.exe stop HermesAgent
sc.exe start HermesAgent

Service recovery#

The agent retries on its own when the server can't be reached. It only stops itself when nothing it can do will help. When it does stop, it exits with an error code (1) rather than a clean stop. Windows then treats it as a failed service and runs the recovery actions described below. This means a host never sits in a state where the service shows Running but nothing is connected.

When the agent keeps retrying#

A server that can't be reached, a dropped connection, or a failed first registration are all treated as temporary. The agent waits and tries again with exponential backoff. The first wait is ReconnectDelaySeconds (default 10) and it doubles after each failed attempt, up to a cap of 5 minutes, plus up to 30% random jitter so a whole fleet doesn't reconnect at the same moment. With the default MaxReconnectAttempts of 0 the agent never gives up on an unreachable server. Both settings live in the agent's configuration file.

When the agent stops itself#

A connection to a server is disabled, with no more retries, when:

• the agent has no certificate and no registration token for that server;
• its certificate has expired (and renewal didn't happen in time);
• the server rejects the agent's authentication or permissions, or rejects the request as invalid;
• MaxReconnectAttempts is set above 0 and that many attempts in a row have failed.

If the agent reports to more than one server, a disabled connection doesn't affect the others. The agent only stops when every server connection has given up. It also stops with an error at startup if its configuration has no usable server entry at all. Before it stops, it writes a line like this to its log:

Every server connection gave up (expired certificate, no registration token and no certificate,
authentication rejected, or retry limit reached - see the error logged for each server).
Nothing is connected and nothing will retry.

Look above that line for each server's own reason, for example Certificate has expired. Connection disabled., Fatal gRPC error (Unauthenticated). Connection disabled., Max reconnect attempts (…) reached. Connection disabled, or No certificate and no registration token configured. Skipping.

Windows recovery actions#

Every Athena installer registers the HermesAgent service with restart-on-failure recovery actions, and the failure counter resets after one day (86,400 seconds). The installers also turn on Windows' "Enable actions for stops with errors" setting (the service's failure flag). Without that setting, Windows only runs recovery actions after a crash, and an agent that stopped itself with an error would stay Stopped.

If the recovery settings can't be applied, the install still goes ahead (HermesCLI prints a warning). To check what a host actually has:

# Show the restart actions and reset period
sc.exe qfailure HermesAgent

# Show whether actions also run for stops with errors (should be TRUE)
sc.exe qfailureflag HermesAgent

sc.exe failure HermesAgent reset= 86400 actions= restart/5000/restart/10000/restart/30000
sc.exe failureflag HermesAgent 1

A restart only helps with temporary problems. If the cause is permanent, such as an expired certificate or rejected authentication, the agent will stop again after each restart. Fix the cause in the log instead. Usually that means re-enrolling the host with a fresh registration token (see Agent Enrollment).

Viewing logs#

The agent writes daily rolling log files in its data directory:

# Follow the most recent daily log file live
Get-Content C:\ProgramData\Hermes\Logs\hermes-*.log -Tail 50 -Wait

# List the log files (newest last)
Get-ChildItem C:\ProgramData\Hermes\Logs\

If the install itself failed, the bootstrap transcript at %TEMP%\athena-install.log records every step it attempted. For a guided, host-side view of connectivity, configuration and enrolment state, use the Agent CLI (HermesCLI). You can also stream a managed agent's logs from the server — see Agent Logs.

Check-in & certificates#

Once enrolled, the Windows agent sends a heartbeat every 30 seconds and a fuller status update periodically, and it holds a client certificate that it renews automatically before expiry. Issued agent certificates are valid for 60 days and begin auto-renewing 7 days before expiry. If a host stops appearing in the fleet, confirm the service is running and can reach the server:

# Is the service up?
Get-Service HermesAgent

# Can the host reach the server's agent (gRPC) port?
Test-NetConnection <server> -Port 8444

# What is the agent complaining about?
Get-Content C:\ProgramData\Hermes\Logs\hermes-*.log -Tail 100

Certificates and the internal certificate authority that issues them are covered under Certificates & PKI.

Troubleshooting the install#

The bootstrap installer stops at the first problem and prints a FAILED: <step> message describing what went wrong. The most common ones and how to resolve them:

Because the install is idempotent, it is always safe to simply run the one-liner again after fixing the underlying cause — it re-points the existing service rather than creating a second one.

Removing the agent#

To retire a Windows host, first remove or revoke it from the console so it stops appearing in the fleet (see Retiring & Removing Agents), then stop and delete the service on the host and remove its files:

# Stop and delete the service (elevated PowerShell)
Stop-Service HermesAgent
sc.exe delete HermesAgent

# Remove the install and data directories
Remove-Item -Recurse -Force 'C:\Program Files\Hermes Agent'
Remove-Item -Recurse -Force 'C:\ProgramData\Hermes'

The agent also added its install folder to the machine Path so that hermescli runs from any prompt (see Agent CLI). After you delete the folder, that entry is left behind. It does no harm, but you can remove it under System Properties → Environment Variables → System variables → Path.

Related#

• Agent Enrollment — generating installers and enrolling hosts.
• Agent CLI (HermesCLI) — the host-side troubleshooting tool.
• AD Agent Deployment — pushing the agent across a domain.
• Agent Binaries & Updates — uploading and promoting agent builds.
• Linux Agent — the same lifecycle on Linux hosts.
• Certificates & PKI — the certificates agents authenticate with.