Screen-Share Helper Binaries

Athena's WebRTC technician screen-share relies on a small remote-helper component that runs alongside the agent on each managed machine. Just like the agent itself, the helper is versioned on the server: you upload a build, mark one version active per operating system, and agents pick up that version for their screen-share sessions. Every build is hashed and signed by your server on upload, and nothing is fetched from the internet — the helper lives entirely inside your network. This page covers how to publish, activate, list, and remove helper builds.

The helper is a separate artifact from the agent binary. It is versioned and activated on its own, so you can refresh the screen-share helper without republishing or pushing a whole new agent build. To manage the agent itself, see Agent Binaries & Updates.

The helper library#

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

Field	Meaning
`id`	Unique identifier (GUID).
`version`	Version string, e.g. `1.3.15`. Rejected if it contains path characters (`..`, `/`, `\`, `:`).
`os`	Target operating system — `Windows` or `Linux`.
`fileName`	Original filename of the uploaded helper.
`fileHash`	SHA-256 hash of the file, computed by the server on upload.
`fileSize`	Size in bytes.
`signature`	Server signature over the hash (see Uploading & signing). `null` only for legacy helpers uploaded before signing existed.
`releaseNotes`	Optional free-text notes.
`isActive`	`true` when this is the current helper for its OS.
`downloadCount`	How many times this helper has been served to agents.
`uploadedBy` / `uploadedAt`	Who uploaded the build and when.

Uploading & signing#

You publish a helper with POST api/helper-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:

Computes the SHA-256 hash of the file.
Signs that hash with your server's certificate authority, storing the signature (Base64) in the signature field.
Records the metadata so the new helper can be resolved for its OS.

Because the signature is produced by your server's own CA, an agent can verify the helper it receives is genuine before using it. The helper is delivered to agents over the same secured connection they already hold with the server — there is no separate download server and no internet fetch.

OS casing matters

The os value must be exactly Windows or Linux — helpers are matched on that casing. Anything else is rejected with 400, as is a missing version or one containing path characters.

The active version#

Agents resolve the active helper for their operating system when they start a screen-share session, so promoting a new build is how you roll it out. Activate a build with POST api/helper-binaries/{id}/activate; this is Admin-only and is written to the audit log. To see what is currently active for an OS, call GET api/helper-binaries/latest?os=Windows (or os=Linux), which returns the newest active build for that platform, or 404 when none is active.

You can confirm which helper version a specific machine is actually running from Screen-Share Diagnostics, which reports the installed helper version per agent — a fast way to spot a device that hasn't picked up the current build yet.

Listing & removing#

GET api/helper-binaries lists every helper build, and an optional os query filters to one platform. Deleting a build with DELETE api/helper-binaries/{id} removes both the database record and the on-disk file — it cannot be undone, so keep the version you want agents to fall back on. Both listing and delete are Admin-only.

Don't delete the active helper out from under your fleet

Before removing an old build, make sure a current version is still active for that OS. Deleting the build agents rely on can leave screen-share unable to resolve a helper until you publish and activate a replacement.

Roles#

Every helper-management action requires the Admin role:

Action	Required role
Upload a helper build	Admin
Activate a helper build	Admin
List helpers / read the latest active helper	Admin
Delete a helper build	Admin

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

REST API#

Method & path	Purpose
`GET api/helper-binaries`	List helper builds (optional `os` filter). Admin.
`GET api/helper-binaries/latest?os={Windows\|Linux}`	The latest active helper for an OS, or `404` when none is active. Admin.
`POST api/helper-binaries`	Upload a helper (multipart: `file`, `os`, `version`, optional `releaseNotes`; server signs it). Admin.
`POST api/helper-binaries/{id}/activate`	Make this helper the active version for its OS. Admin.
`DELETE api/helper-binaries/{id}`	Delete a helper build (record + file). Admin.

PowerShell#

The Athena module ships cmdlets for the whole helper lifecycle:

Cmdlet	Purpose
`Get-AthenaHelperBinary`	List helpers, filter by `-Os` (`Windows`/`Linux`), or fetch the `-Latest` active build for an OS. Admin.
`Send-AthenaHelperBinary`	Upload a build: `-Path`, `-Os` (`Windows`/`Linux`), `-Version`, optional `-ReleaseNotes`. Server signs it. Admin.
`Enable-AthenaHelperBinary`	Make a helper the active version for its OS, by `-Id` (accepts the pipeline). Admin.
`Remove-AthenaHelperBinary`	Permanently delete a helper by `-Id`; prompts unless you pass `-Force`. Admin.

# Publish a new Windows helper and make it the active version
$helper = Send-AthenaHelperBinary -Path "C:\Build\RemoteHelper.exe" -Os Windows -Version "1.3.15" -ReleaseNotes "Screen-share fixes"
Enable-AthenaHelperBinary -Id $helper.Id

# Confirm what's active, and clean up an older build
Get-AthenaHelperBinary -Latest -Os Windows
Get-AthenaHelperBinary -Os Windows | Where-Object { $_.Version -eq "1.3.10" } | Remove-AthenaHelperBinary -Force

See the PowerShell Module reference for full cmdlet details.

Air-gapped by design

Helper versioning never reaches out to the internet. You bring a new helper build onto the isolated network, upload it to your server, and agents pick it up over the connection they already hold — signed by your own certificate authority. The whole path stays inside your perimeter. See Air-Gapped Operation.