Agent Settings

Agent Settings are the fleet-wide defaults that govern how every agent behaves: how often it checks in, when the server considers it offline, how frequently it takes a full inventory, how long its certificate lasts, where deployment packages land, and how much it logs. You manage them in one place — Settings → Agents — and the two most time-sensitive values (check-in and inventory cadence) are pushed to connected agents immediately, with no restart. It is the client-policy tuning a System Center or PDQ admin expects, kept entirely on your own server.

Where to find it#

Open Settings and choose the Agents tab. It is divided into sub-tabs; the two that hold fleet behaviour are:

• Configuration — heartbeat, certificate, deployment, display formats and log level. This is the sub-tab this page focuses on.
• Updates — the agent binary library, push updates, and the Auto Update toggle (see also Agent Binaries & Updates).

Reading Agent Settings and saving changes both require the Admin role. The whole Settings area is Admin-only, and every save is written to the audit log (see Auditing).

Heartbeat & connectivity#

The Heartbeat Settings section controls how agents check in and how the server decides an agent is online. Three values work together:

The console recommends keeping the timeout at least three times the interval so that one or two dropped heartbeats don't briefly flag a healthy agent as offline. With the shipped configuration (59 s interval, 600 s timeout) an agent that goes silent is marked offline after 10 minutes. For exactly how the two values are applied, see Agent Status & Health.

Changes take effect live#

When you change the Heartbeat Interval or Full Inventory Interval and save, the server pushes the new cadence to every currently connected agent over the connection it already holds. Agents apply it on the spot — no restart and no reinstall. Agents that are offline at the time pick up the new values the next time they connect. The other Agent Settings below are stored on the server and applied through their own mechanisms (for example at the next certificate renewal, or the next time an agent's log stream is opened) rather than being broadcast immediately.

Certificate validity & auto-renewal#

The Certificate Settings section governs the lifetime of the per-agent certificates Athena issues (see Certificates & PKI):

Shorter validity is stricter (certificates rotate more often); the renewal threshold should stay comfortably below the validity so agents always renew before the current certificate expires.

Deployment & display defaults#

The remaining Configuration sections set operational defaults and how agent metrics are presented in the console:

Auto Update#

On the Updates sub-tab, the Auto Update toggle (autoUpdateEnabled) decides whether agents automatically pull and apply a new binary when one becomes available, or wait for you to push it explicitly. It is off by default — updates are an explicit, deliberate action unless you turn this on. Full details of the binary library and pushing versions are on Agent Binaries & Updates.

Roles#

Reading and changing Agent Settings is restricted to Admin users — the entire Settings area, its REST endpoints, and the matching PowerShell cmdlets all require the Admin role. Operators and Viewers can see agent state on the Dashboard and Agent Details but cannot change these fleet defaults. See Roles & Permissions.

REST API#

Agent Settings are exposed under api/settings/agent. Reading them requires the settings.view permission and saving requires settings.manage; with the built-in roles, both are held only by Admin (see Permission Model).

An update replaces the whole Agent group#

PUT api/settings/agent is a full replacement, not a patch. The same object also carries the RustDesk, screen-share relay and session recording options, and every one of them is written from the body you send. A field you leave out is not left alone: it is saved as its built-in default. For example, a body that only sets the heartbeat values would also turn off RustDesk and browser screen-share and clear the stored relay key, fleet default password and TURN secret.

The safe pattern is always read, change, write back: GET the current object, change only the fields you mean to, and PUT the whole object back.

# 1. Read the current settings (the object is in the "data" property)
GET api/settings/agent

# 2. Change only what you need, e.g. slow the fleet down on a large network:
#    "heartbeatIntervalSeconds": 60, "heartbeatTimeoutSeconds": 180,
#    "statusUpdateIntervalSeconds": 600

# 3. Send the complete object back, secret fields still reading "********"
PUT api/settings/agent

Invalid values return 400; an unauthenticated call returns 401, and a caller without the required permission 403. A successful update returns a confirmation message.

Secret fields are masked#

Three agent settings are live credentials. The REST API never returns their stored values:

How these fields behave over the REST API:

• On read — if a value is stored, GET api/settings/agent and GET api/settings return "********" in its place. If nothing is stored, the field comes back null, so you can still tell whether a secret is set.
• To keep a secret — send "********" back unchanged. The server keeps the stored value. This is what makes the read, change, write back pattern safe.
• To rotate a secret — send the new value in that field. It is written as given.
• To clear a secret — send null or an empty string, or leave the field out.

The Settings → Agents screen is separate from the REST API and is unaffected by this masking. In the audit log, a changed secret is recorded as changed but its value is hidden. A secret sent back as "********" counts as unchanged, so it adds no audit entry.

PowerShell#

The PowerShell module reads and writes settings by category with Get-AthenaSettings and Set-AthenaSettings. The reliable pattern is to fetch the current object, change a field, and put it back:

# Inspect the current agent defaults
Get-AthenaSettings -Category Agent

# Fetch, tweak, and save back
$agent = Get-AthenaSettings -Category Agent
$agent.HeartbeatIntervalSeconds = 60
$agent.HeartbeatTimeoutSeconds  = 180
Set-AthenaSettings -Category Agent -Settings $agent

The object returned by Get-AthenaSettings -Category Agent has the secret fields set to ********. Passing it back unchanged keeps the stored secrets. To rotate one, set that property to the new value before you save.

Get-AthenaSettings accepts -Category General, Security, Agent, Scheduler, Database or Logging (omit it to get everything). Set-AthenaSettings supports the writable categories (General, Security, Agent, Scheduler, Logging) and supports -WhatIf / -Confirm so you can preview a change before applying it. All of these require an Admin session.

Auditing#

Every save to Agent Settings is recorded in the audit log with the Admin who made the change, so you can see who adjusted heartbeat cadence, certificate lifetime or auto-update, and when. If you forward audit events to a SIEM, those changes flow there too — see Audit Forwarding to SIEM.

Recommendations#

• Keep Heartbeat Timeout ≥ 3× Heartbeat Interval so a couple of missed heartbeats don't cause false "offline" flapping.
• On large fleets, prefer a longer Full Inventory Interval to reduce load; leave the heartbeat short enough that the Dashboard still feels responsive.
• Keep the Auto-Renewal Threshold well below Certificate Validity so certificates always renew before they expire.
• Leave Auto Update off unless you specifically want hands-off upgrades; pushing versions deliberately gives you a controlled rollout.
• Because interval changes push to connected agents instantly, make cadence adjustments during a quiet window and watch the Dashboard to confirm agents stay online.