SG SealGrid Athena Docs
Docs / Agents & fleet / Windows Agent

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#

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.

The script contains no secret

The only value pre-filled into the downloaded script is your server's host address. There is no embedded password or token — credentials are entered at runtime, and the registration token the installer mints for you is single-use and expires in ten minutes. For the download/generate flow in the console, see Agent Enrollment.

Other ways to install

The bootstrap one-liner is the quickest path, but you can also enrol Windows hosts at scale with a pre-created registration token and a downloadable ZIP bundle, or push the agent to machines across a domain with AD Agent Deployment. For offline networks, see Air-Gapped Operation.

Files & service layout#

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

PathWhat it holds
C:\Program Files\Hermes Agent\Install directory — the agent executable (Hermes.Agent.exe) and its appsettings.json configuration.
C:\ProgramData\Hermes\Data directory — persisted enrolment state, inventory cache, and the agent's certificate.
C:\ProgramData\Hermes\Logs\hermes-*.logRolling agent log files, one per day, with the 30 most recent files retained.
%TEMP%\athena-install.logTranscript from the bootstrap installer — for troubleshooting the install itself (password-redacted).

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 or a reboot without intervention.

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

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:

MessageWhat it means & how to fix it
Run this script as AdministratorThe one-liner must run in an elevated PowerShell. Start PowerShell with Run as administrator and paste the command again.
FAILED: Login rejectedThe username/password was wrong or the server URL/port is unreachable. Re-check the credentials and confirm the API port (default 8443) is reachable from the host.
FAILED: Resolve latest binaryNo active Windows agent binary exists on the server. Upload and activate one under Agent Binaries & Updates first. (The Agent Installer card disables the Windows button until a binary is available.)
FAILED: Mint tokenThe account you signed in with lacks the rights to create registration tokens. Use an account with the appropriate role.
FAILED: Verify binaryThe downloaded file's SHA-256 did not match the server-reported hash (or the server reported no hash). The installer refuses to install an unverifiable or tampered file — retry the download; if it persists, re-upload the binary on the server.
FAILED: Verify onlineThe service was installed but did not reach Running. Check the agent logs under C:\ProgramData\Hermes\Logs\ and confirm outbound reachability to the agent port (default 8444).

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'

Deleting C:\ProgramData\Hermes removes the host's enrolment state and certificate. If you want to re-enrol later, run the installer again — it will register the host as a fresh agent.

© 2026 SealGrid · sealgrid.ai · Sealed by design.