Agent Enrollment

Bringing a machine under management is a copy-and-paste. In the console, open Settings → Agent, generate an installer for Windows or Linux, copy the one-liner it gives you, run it on the target, and sign in with your credentials. The Hermes agent then connects outbound only to the server on port 8444 and authenticates with a per-agent X.509 certificate — there are no inbound ports on the agent.

How enrollment works#

The quickest path uses the built-in installer generator — nothing to hand-edit:

1. In the console, open Settings → Agents and stay on the Configuration sub-tab (it's the default). Scroll down to the Agent Installer card — it appears only if you're signed in as an Admin — and click Windows or Linux.
2. The server generates the installer and reveals a copy-to-clipboard one-liner with your server address already filled in.
3. Run the one-liner on the target machine and provide your credentials when prompted. The agent installs, registers, and receives its certificate automatically.

Issued certificates are valid for 60 days (key size 2048) and auto-renew 7 days before expiry. The agent runs a renewal check every 6 hours.

Generate an installer (Settings → Agents → Configuration)#

The Agent Installer card lives on the Configuration sub-tab of Settings → Agents (the default sub-tab) — scroll down past the Heartbeat, Certificate, Deployment and Log Level sections to reach it. The card is shown only to Admin users. It is the easiest way to enroll a host. Pick the OS, and the console:

• downloads the ready-to-run install script, and
• reveals a copy-to-clipboard one-liner with your server address already embedded — nothing to edit by hand.

Copy the one-liner, run it on the target, and provide your credentials when prompted. Only Windows and Linux are supported (macOS is not). The generated commands look like:

Windows (PowerShell)#

iex (New-Object Net.WebClient).DownloadString('https://<server>:8443/...')

Linux (download-then-run)#

The Linux installer is deliberately not a curl | bash one-liner — it downloads first, then runs:

curl -fsSLk https://<server>:8443/... -o /tmp/athena-linux-agent-install.sh && sudo bash /tmp/athena-linux-agent-install.sh

Unattended enrollment with tokens#

For scripted or unattended rollout — where no one is at the keyboard to enter credentials — use a registration token instead. Tokens are created in the console or via the API, and each carries an expiration and a max-usage count.

Default token validity is governed by the Security:AgentTokenValidityDays setting (90). For the full token lifecycle — validity, usage limits, revoke vs. delete, and the four PowerShell cmdlets — see Registration Tokens.

The installer and binary endpoints live under api/agent-binaries:

Agent configuration#

The agent's appsettings.json has an Agent:Servers[] array. Each entry has Name, Url (e.g. https://localhost:8444), RegistrationToken, and Enabled. Multiple servers are supported, so a single agent can be multi-homed.

"Agent": {
  "Servers": [
    {
      "Name": "Primary",
      "Url": "https://localhost:8444",
      "RegistrationToken": "<token>",
      "Enabled": true
    }
  ]
}

Other agent keys:

Log paths:

• Windows: C:\ProgramData\Hermes\Logs\hermes-.log
• Linux: /var/lib/hermes/logs/hermes-.log

Certificates & PKI#

The server generates its Root CA on first run. Agent certificates are issued, renewed, and revoked through the PKI API:

Agent self-update#

The server stores agent binaries under AgentUpdate:StoragePath ("./agent-binaries"). AutoUpdateEnabled is false by default. Push updates through the agent-updates API:

For the full lifecycle — uploading and signing builds, choosing the active version per OS, pushing to selected agents, and reading update history — see Agent Binaries & Updates.