Linux Agent

The Hermes agent runs on Linux as well as Windows. On a Linux host it installs as a systemd service called hermes-agent, checks in to the server over the same secured connection your Windows agents use, and takes part in the same fleet operations — inventory, software deployment, remote commands, and compliance. This page covers what the Linux agent is, where it puts its files, and how to manage and troubleshoot it day to day. For generating the installer command itself, see Agent Enrollment.

Requirements#

• A 64-bit Linux distribution with systemd (the agent installs and runs as a systemd service and manages itself with systemctl).
• Root / sudo to install — the installer writes the binary, its configuration, and the service unit 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).
• A Linux agent binary must already be uploaded and marked active on the server — the installer downloads the latest active Linux build. See Agent Binaries & Updates.

The installer prefers jq and uses sha256sum (or openssl) to verify the downloaded binary, but it falls back gracefully when jq is absent.

Installing the agent#

In the console, open Settings → Agents (Configuration sub-tab) and, in the Agent Installer card, click Linux to copy the bootstrap command. Unlike the Windows one-liner, the Linux installer is deliberately download-then-run rather than a curl | bash pipe, so its interactive prompts work correctly:

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

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

1. Prompts for the server host, API port (default 8443), agent 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 Linux agent binary.
3. Mints a short-lived (10-minute), single-use registration token labelled with the hostname — so no long-lived secret is left lying around.
4. Downloads the binary and verifies its SHA-256 against the server-reported hash before installing; a mismatch aborts the install.
5. Installs the binary, writes the agent configuration, installs and enables the hermes-agent systemd service, and confirms the service comes up.

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 /var/log/athena-install.log (or /tmp/athena-install.log if that path isn't writable); the password is never included.

Files & service layout#

A standard install lays the agent out in predictable locations:

The agent's configuration file (/opt/hermes/appsettings.json) is written with tight permissions because it contains the enrolment token until the host has registered. The agent logs to both its own log files and to the systemd journal, so journalctl works out of the box.

Managing the service#

Because the agent is a normal systemd service, you manage it with the tools you already use. The service is enabled to start on boot and is configured to restart on failure.

# Status, start, stop, restart
sudo systemctl status hermes-agent
sudo systemctl start hermes-agent
sudo systemctl stop hermes-agent
sudo systemctl restart hermes-agent

# Enable / disable start-on-boot
sudo systemctl enable hermes-agent
sudo systemctl disable hermes-agent

Viewing logs#

There are two equivalent ways to read what the agent is doing:

# Follow live output via the systemd journal
journalctl -u hermes-agent -f

# Last 50 journal lines
journalctl -u hermes-agent -n 50

# Or read the agent's own daily log files
sudo tail -f /var/lib/hermes/logs/hermes-*.log

Log verbosity follows the fleet-wide log-level policy you set for agents in the console. See Agent Settings and Server Logging.

What the Linux agent does#

A registered Linux host is a first-class member of the fleet. The Linux agent supports:

Script interpreters#

Command and script steps run through the interpreter available on the host. The Linux agent detects and uses bash (typically /bin/bash) and, when installed, PowerShell (pwsh, from /usr/bin/pwsh or /usr/local/bin/pwsh). If a required interpreter isn't present, steps that need it will report an error rather than silently skipping.

Inventory sources#

Linux inventory is gathered from the standard system sources rather than Windows APIs — for example OS details from /etc/os-release, CPU details from /proc/cpuinfo, installed software from the native package manager (dpkg, rpm, or pacman depending on the distribution), and services from systemctl. The results feed the same Inventory views, Collections, and Reports as Windows hosts. See Inventory.

Check-in & certificates#

Once enrolled, the Linux agent behaves like any other agent: it sends a heartbeat every 30 seconds and a fuller status update periodically, and it holds a client certificate it renews automatically before expiry. If a host stops checking in, confirm the service is running and can reach the server:

# Is the service up?
sudo systemctl status hermes-agent

# Can the host reach the server's agent port?
curl -vk https://<server>:8444/ 2>&1 | head

# What is the agent complaining about?
journalctl -u hermes-agent -n 100 --no-pager

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

Removing the agent#

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

sudo systemctl disable --now hermes-agent
sudo rm -f /etc/systemd/system/hermes-agent.service
sudo systemctl daemon-reload
sudo rm -rf /opt/hermes /var/lib/hermes

Related#

• Agent Enrollment — generating installers and enrolling hosts.
• Agent CLI (HermesCLI) — the host-side troubleshooting tool.
• Agent Binaries & Updates — uploading and promoting agent builds.
• Inventory — what's collected and how to query it.
• Software Deployment — building and targeting packages.
• Air-Gapped Operation — offline enrolment and operation.