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 defaults (30 s interval, 90 s timeout) an agent has to miss three heartbeats in a row before it goes offline.

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. Both operations are Admin-only.

A typical update body:

# Slow the fleet down a little on a large network
PUT api/settings/agent
{
  "heartbeatIntervalSeconds": 60,
  "heartbeatTimeoutSeconds": 180,
  "statusUpdateIntervalSeconds": 600,
  "certificateValidityDays": 30,
  "certificateRenewalThresholdDays": 7,
  "autoUpdateEnabled": false,
  "defaultDeploymentFolder": "/data/packages",
  "defaultLogLevel": "Information"
}

Invalid values return 400; an unauthenticated call returns 401, and a non-Admin caller 403. A successful update returns a confirmation message.

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

# Or change just a couple of fields with a hashtable
Set-AthenaSettings -Category Agent -Settings @{
  HeartbeatIntervalSeconds    = 60
  StatusUpdateIntervalSeconds = 600
}

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.