Agent Binaries & Updates

Athena keeps a library of agent binaries on the server and lets you decide which version each operating system runs. You upload a new agent build, mark it active for its OS, then push that version to whichever agents you choose. The server streams the signed binary to each connected agent over the same connection it already uses — no download server, no internet, and every push is written to the audit log. It is the fleet-wide "client version management" a System Center admin expects, kept entirely inside your network.

The binary library#

Each uploaded build is stored as an agent binary record. Binaries are keyed by Os and Version, and each OS has at most one active version at a time. Every record tracks:

Uploading & signing#

You upload a build with POST api/agent-binaries as a multipart form (file, os, version, and optional releaseNotes). Uploads are Admin-only and capped at 500 MB. As it streams the file to disk the server:

1. Computes the SHA-256 hash of the binary.
2. Signs that hash with the CA private key — an RSA / SHA-256 (PKCS#1) signature, stored Base64 in the signature field.
3. Records the metadata and marks the new binary isActive = true for its OS.

Because the signature is produced by your server's own certificate authority, an agent can verify the build it receives is genuine before applying it. Binaries are written to disk under the path configured by AgentUpdate:StoragePath (default ./agent-binaries).

The active version#

Exactly one binary per OS is the active version. A freshly uploaded build becomes active automatically, but you can promote any earlier build with POST api/agent-binaries/{id}/activate — that deactivates every other binary for the same OS and flips the chosen one on. Activation is Admin-only.

The active version is what push updates and the agent installer use when no explicit version is given. GET api/agent-binaries/latest/{os} returns the current active binary for an OS (404 if none has been uploaded yet), and the bootstrap installer for an OS is blocked until at least one binary exists for it.

Pushing updates#

To move agents onto a version, push it to a chosen set of agents with POST api/agent-updates/push (Admin-only). The body lists the target agents and, optionally, the version and a force flag:

# Update three agents to the latest active version for their OS
POST api/agent-updates/push
{
  "agentIds": ["a1…", "b2…", "c3…"],
  "targetVersion": null,
  "force": false
}

The server processes each agent independently:

1. Looks up the agent to learn its OS and current version, then resolves the correct binary — the named version, or the OS's latest active build when targetVersion is null.
2. Writes an update-history record and sends the agent an update notification (target version, hash, size, signature, and the force flag) over its existing connection.
3. Streams the signed binary to the agent over that connection — there is no separate download step for connected agents.
4. Writes an audit event for the push (see the callout below).

The response summarises the batch: successCount, failedCount, a per-agent results map, and an updateIds map linking each agent to its history record. An agent that is not currently connected can't be reached, so its history row is marked Failed with "Agent not connected" and it is counted as failed — reconnect the agent (or wait for it) and push again.

Update history & status#

Every push creates an update-history record you can review per agent or fleet-wide. Each record tracks the agent, fromVersion → toVersion, who initiated it, timestamps, and a status:

Completion is confirmed by the agent itself: when an agent reconnects reporting a version that matches an in-flight update (one still Pending, Downloading, or Installing), the server marks that record Completed. Read history with GET api/agent-updates/history (optionally filtered by agentId, default limit 50); history reads are available to Operator or Admin.

Configuration#

With auto-update off (the default), nothing moves until an admin pushes it, so you stay in control of exactly when and where a new agent version lands. See Configuration for how to change these settings.

Roles#

The permission split follows the risk of each action:

Callers without the required role receive 403; unauthenticated callers receive 401. See Roles & Permissions.

REST API#

The installer-facing endpoints of api/agent-binaries (download, install-script, and ZIP bundle) are covered under Agent Enrollment.

PowerShell#

The Athena module ships cmdlets for the whole binary-and-update lifecycle:

# Publish a new Windows build and make it the active version
$bin = Send-AthenaAgentBinary -Path "C:\Build\Hermes.Agent.exe" -Os Windows -Version "1.2.42" -ReleaseNotes "Bug fixes"
Enable-AthenaAgentBinary -Id $bin.Id

# Roll it out to every online agent, then review the results
Get-AthenaAgent -Online | Send-AthenaAgentUpdate
Get-AthenaAgentUpdateHistory -Limit 20

See the PowerShell Module reference for full cmdlet details.