Agent Install Bundle

The install bundle is a self-contained ZIP you download for a specific agent version and copy onto a Windows host to enrol it. It packs the agent executable, a pre-filled configuration, and a PowerShell installer, so a technician can install and connect an agent without hand-editing any files. You can optionally embed a short-lived, one-shot registration token in the ZIP for zero-touch enrolment, and override the server URL the agent will connect to. Because the bundle carries everything it needs, it is the enrolment method of choice for air-gapped, hardened, or mass-imaging environments where the machine cannot fetch a script from the server.

What's supported#

The install bundle is Windows-only today — the dialog shows Linux bundle coming soon, and requesting a bundle for a Linux binary is refused. To enrol Linux hosts, use the Linux agent one-line installer instead. On the target Windows host you need:

• Windows 10/11 or Windows Server 2019+ (x64),
• PowerShell 5.1 or later,
• local Administrator privileges to run the installer, and
• outbound TCP access to the server's gRPC port (8444 by default) — see Network Ports.

Downloading a bundle is an Admin-only action. Building an agent binary available to bundle is covered in Agent Binaries & Updates; if no active binary has been uploaded for an operating system, there is nothing to bundle.

Downloading a bundle#

Open Settings → Agent → Updates. Each uploaded binary version in the Agent Binaries list has a Download Bundle action. Choosing it opens the Download Agent Bundle dialog with three choices:

The download is a ZIP named HermesAgent-<version>-windows.zip. Every bundle download is written to the audit log, recording whether a token was embedded and its lifetime, so you always know which bundles carry a live credential.

The embedded token is one-shot#

An embedded registration token is minted with a single use. The first agent that registers with it consumes it; the token then cannot enrol any further machines even if its lifetime window has not elapsed. This keeps a leaked bundle from being replayed to stand up additional agents.

The practical consequence: a token-embedded bundle enrols one machine. For a mass-imaging or golden-image workflow — where the same ZIP is baked into an image and applied to many machines — do not embed a token. Instead download the bundle without a token and supply a token at install time (a token minted for reuse), or mint a fresh token per machine. See Registration Tokens for one-time vs. reusable tokens and their expiry.

What's inside the ZIP#

Installing on the target machine#

Copy the ZIP to the Windows host and extract it. When the bundle has an embedded token, installation is zero-touch — right-click Install-HermesAgent.ps1 and choose Run with PowerShell as Administrator, or from an elevated PowerShell prompt:

Set-Location <path-to-extracted-zip>
.\Install-HermesAgent.ps1

The installer:

• copies the agent files to C:\Program Files\Hermes Agent\,
• adds that install directory to the machine-wide system PATH,
• registers the HermesAgent Windows service (auto-start, runs as LocalSystem),
• configures restart-on-failure actions, and
• starts the service.

Within a heartbeat or two (the default heartbeat is 30 seconds) the machine appears on the Agents page and turns Online. If a token was embedded, it is consumed on this first registration.

Manual install (no embedded token)#

If you downloaded the bundle without a token, supply one at install time with the installer's -Token parameter. You can also override the server URL with -ServerUrl:

# Supply a registration token at install time
.\Install-HermesAgent.ps1 -Token "your-registration-token"

# Override the server URL as well
.\Install-HermesAgent.ps1 -ServerUrl "https://athena.example.com:8444" -Token "your-token"

When -ServerUrl and -Token are omitted, the installer uses the values already in the bundle's appsettings.json. Two more parameters are available: -ServerName (the name of the server entry to override, default primary) and -InstallPath (the install directory, default C:\Program Files\Hermes Agent). Mint a token in Settings → Security → Tokens, or see Registration Tokens.

Verifying and uninstalling#

On the machine, confirm the service is running and check the agent's logs:

Get-Service HermesAgent

# Recent agent logs
Get-Content "C:\ProgramData\Hermes\Logs\hermes-*.log" -Tail 50

The agent's runtime data (its certificate, state, and logs) lives under C:\ProgramData\Hermes\. To remove the agent, from an elevated prompt:

Stop-Service HermesAgent -Force
sc.exe delete HermesAgent
Remove-Item -Recurse -Force "C:\Program Files\Hermes Agent"

# To also remove the agent's data (certificate, state, logs)
Remove-Item -Recurse -Force "C:\ProgramData\Hermes"

For an orderly, server-side retirement of an already-enrolled agent (revoking its certificate and removing it from the fleet), see Retiring & Removing Agents.

Troubleshooting#