Remote Helper & HermesCLI Binaries

Besides the agent itself, your Athena server hosts two smaller components that agents download from it: the Remote Helper, which powers WebRTC technician screen-share on Windows, and HermesCLI, the local agent command-line tool. You upload one build of each per operating system, the server hashes and signs it with your own certificate authority, and agents pull it over the connection they already hold. Nothing is fetched from the internet. This page covers the Settings screens, the one-build-per-OS rule, how agents pick builds up, and the REST API and PowerShell cmdlets.

Where to manage them#

Open Settings → Agents → Updates. The Updates sub-tab is split into five views, shown as a strip of buttons along the top: Rollout & auto-update, Agent binaries, Push & history, Remote Helper and HermesCLI. The view you pick is kept in the page address (?view= on /settings/agent/updates), so you can bookmark or share a link to one view, and the browser's Back button works. The last two views are covered here.

You only see these two views' contents if you hold the binaries.manage permission (see Permissions). Without it the section is empty.

The per-OS table#

Each view shows one row per operating system. It is not a version history, because the server keeps only one build per OS (see below). A row with nothing stored reads Not uploaded. Otherwise it shows:

Uploading a build#

1. In the row for the OS you want, click the upload button. A form titled Upload for <OS> opens below the table.
2. Check the Operating System. It is preset to the row you clicked, and you can change it here.
3. Enter a Version (required, e.g. 1.2.12). The file picker stays disabled until you do. You can also add optional Release Notes.
4. Click Browse Files and choose the file. It uploads straight away. Files can be up to 500 MB.

If it succeeds you see the toast Remote helper uploaded or HermesCLI uploaded, the form closes, and the table shows the new build. If the server rejects the input (for example a version containing path characters), the reason appears in red under the form. Any other failure reads Failed to upload binary. To leave without uploading, use the cancel button in the form header.

The upload screen does not care about the file name: the server stores the Remote Helper as Hermes.RemoteHelper.exe, and HermesCLI as HermesCLI.exe on Windows and HermesCLI on Linux and macOS. Agents use those same names when they place the file.

One build per OS#

The server keeps exactly one build per operating system for each of the two components. A new upload works like this:

1. The server writes the file to disk and calculates its SHA-256 hash while it streams in.
2. It signs that hash with your server's certificate authority. If signing fails, the upload fails and nothing changes.
3. It records the build as the active build for its OS. If you upload a version that is already stored for that OS, that record is overwritten in place and keeps its current active setting.
4. Only after all of that succeeds does it delete every older build for that OS, including the stored files.

So a failed upload always leaves the previous build in place. Removing the old builds is best effort: if an old file can't be deleted right now (for example, an agent is still downloading it), the server logs a warning, keeps the file, and tries again on the next upload for that OS. The new build is already live either way. There is no separate activate step and no rollback list in the UI. To go back to an earlier version, upload that build again.

How agents pick up a build#

Agents ask the server for the newest active build for their OS, over their existing secured agent connection. There is no separate download server or HTTP download URL. If nothing is stored for that OS, the server tells the agent so and the agent carries on normally.

• HermesCLI is requested on every connect. The agent first compares the server's hash with the one it recorded for the copy it already has. If they match, it keeps its current copy. Otherwise it downloads the new build and checks two things before it uses it: the SHA-256 must match the hash the server announced, and the signature must verify against the CA certificate the agent already holds locally. A build with no signature is refused. Only after both checks pass is the file swapped in. On macOS the agent then signs the binary for local use. To roll a new HermesCLI out, upload it: each agent gets it on its next connect.
• Remote Helper: the Windows agent pulls it when it starts, once it reaches a server, and checks it again before a screen-share session. The Linux and macOS agents do not use a screen-share helper. Use Screen-Share Diagnostics to see which helper version a specific machine has installed.

Problems on the agent side are written to the agent log (see Agent Logs). HermesCLI lines start with CliProvision:, for example CliProvision: HermesCLI <version> failed verification: … NOT placing it. or CliProvision: server sent an unsigned CLI; refusing it.

Permissions#

Every Remote Helper and HermesCLI action, including listing, requires the binaries.manage permission. Of the built-in roles, only Admin has it. Operator's binaries.view is not enough here. You can grant binaries.manage to a custom role (see Roles and the Permission Model). In the UI, every upload checks the permission again when it runs. Over REST, unauthenticated callers get 401 and callers without the permission get 403.

REST API#

The two components have identical endpoints under different base paths. Use api/helper-binaries for the Remote Helper and api/cli-binaries for HermesCLI. Responses use the standard Athena envelope (the result is in data).

Each build record contains:

An upload returns 400 with one of these messages when the input is invalid:

• No file provided
• OS must be 'Windows' or 'Linux' (helper) or OS must be 'Windows', 'Linux' or 'MacOS' (HermesCLI). Casing matters.
• Version is required
• Version contains invalid characters: the version contains .., /, \, : or another character that isn't allowed in a file name.

Any other failure returns 500 (Failed to upload helper binary / Failed to upload HermesCLI).

# Publish a new HermesCLI build for Linux
curl -H "Authorization: Bearer $TOKEN" \
  -F "file=@./HermesCLI" -F "os=Linux" -F "version=1.2.25" \
  https://athena.example.local:8443/api/cli-binaries

# What will a connecting macOS agent receive?
curl -H "Authorization: Bearer $TOKEN" "https://athena.example.local:8443/api/cli-binaries/latest?os=MacOS"

For authentication options, including long-lived tokens, see API Reference and API Tokens.

PowerShell#

The Athena module has cmdlets for the Remote Helper. There are no HermesCLI binary cmdlets yet, so use the Settings view or the REST API for those.

# Replace the Windows helper and confirm what agents will receive
Send-AthenaHelperBinary -Path "C:\Build\Hermes.RemoteHelper.exe" -Os Windows -Version "1.3.22" -ReleaseNotes "Screen-share fixes"
Get-AthenaHelperBinary -Latest -Os Windows

See the PowerShell Module reference for full cmdlet details.

Storage & backup#

Uploaded builds are stored under the server's bulk-storage root (Storage:DataRoot), one folder per OS and version:

The server must be able to write to these folders. If it can't, the error message names the path and the setting that moves it. Back them up together with the rest of the data root (see Data Directories). The builds can be uploaded again, but on an air-gapped network that is inconvenient.