Agent Configuration File (appsettings.json)

Each managed host runs the Hermes agent, and the agent reads its settings from a local appsettings.json file next to its executable. This page is the reference for the Agent section of that file: what every key means, its default, where the file lives on Windows and Linux, how to override values with environment variables, and how changes take effect. For most day-to-day edits you should let the Agent CLI (HermesCLI) write the file for you — but when you're templating a mass rollout or reviewing a host by hand, this is the map.

Where the file lives#

The agent loads appsettings.json from its install directory. The data directory (state, certificate, logs) is separate and controlled by the DataPath key below. Edit the file with an editor that preserves UTF-8 without a byte-order mark, and keep a backup before large changes.

To find the exact paths in use on a given host — including whether each file currently exists — run HermesCLI debug paths. For where log files are written and how to raise the log level, see Agent Logs.

Overall shape#

All agent settings live under a single Agent object. A minimal, production-shaped file looks like this:

{
  "Agent": {
    "Servers": [
      {
        "Name": "production",
        "Url": "https://athena.example.com:8444",
        "RegistrationToken": "<one-time-token>",
        "Enabled": true
      }
    ],
    "HeartbeatIntervalSeconds": 30,
    "StatusUpdateIntervalSeconds": 60,
    "DataPath": "",
    "ValidateServerCertificate": true,
    "CertificateRenewalDays": 7,
    "ConnectionTimeoutSeconds": 30,
    "ReconnectDelaySeconds": 10,
    "MaxReconnectAttempts": 0
  }
}

The file also carries a Serilog section that controls agent logging (level, sinks, and the log-file path) — see Agent Logs — and may include the optional UpdateScanner and RemoteSession blocks described below.

The Agent section, key by key#

Server connections#

Servers is an array — an agent can report to more than one server at once (multi-homing). Each entry has four fields:

You rarely need to hand-edit this array: HermesCLI config server add / disable / enable / remove maintains it safely. For the concepts and reporting behaviour of multi-homed agents, see Multi-Homed Agents; for how tokens are created and scoped, see Registration Tokens and Agent Enrollment.

Optional feature blocks#

Two optional top-level blocks tune specific agent behaviours. Both are safe to omit.

Windows Update scanning#

On Windows, the agent can scan for missing updates against an offline WSUS catalog file. This is disabled by default and enabled with:

  "UpdateScanner": {
    "Enabled": true
  }

For the full offline-update workflow — supplying the catalog and managing update scans and deployment — see Windows Update Management.

Screen-share helper gate#

A single agent-side switch controls whether the agent is willing to launch the screen-share helper when the server authorises a session:

  "RemoteSession": {
    "EnableHelperLaunch": true
  }

Setting EnableHelperLaunch to false prevents this host from ever starting a screen-share session, regardless of server-side settings. Note that this switch only gates willingness: an attended session still requires the per-session consent prompt and on-screen indicator, and unattended access still requires it to be allowed for the agent on the server. See Remote Commands & Desktop, Unattended Access, and Screen-Share Helper Binaries.

Environment-variable overrides#

Any value in the file can be supplied — or overridden — through an environment variable, which is convenient for container images and templated deployments where you'd rather not bake secrets into a JSON file. Use the standard nested form, joining path segments with a double underscore (__):

# Linux / container
Agent__HeartbeatIntervalSeconds=30
Agent__ValidateServerCertificate=true
Agent__Servers__0__Url=https://athena.example.com:8444
Agent__Servers__0__RegistrationToken=<one-time-token>

Array entries are addressed by index (Servers__0, Servers__1, …). Environment variables take precedence over the values in appsettings.json, so a variable set on the service or container wins over the file.

How changes take effect#

Except for the logging level (which the agent hot-reloads), edits to appsettings.json apply when the agent restarts. After changing any value:

# Windows
HermesCLI service restart

# Linux
sudo systemctl restart hermes-agent