Screen-Share Diagnostics

When WebRTC technician screen-share won't connect to one particular machine, Screen-Share Diagnostics gathers everything you need to find out why into a single per-agent view: the installed remote-helper version, the most recent screen-share session and how it ended, whether remote control was used, and a live check that the optional media relay is reachable. It's the “one device is misbehaving — what's wrong with it?” support surface, available from the console, the REST API, and PowerShell.

What diagnostics report#

A single diagnostics call returns the following for the selected agent. Each field is composed from data the server already holds — inventory, the audit trail, and a live relay probe — so there is no extra agent round-trip beyond the optional relay test.

The Screen-Share Diagnostics card#

In the console, open an agent from the fleet list and scroll to the 🩺 Screen-Share Diagnostics card on its details page. The card is shown only when both of these are true:

• WebRTC screen-share is enabled server-side. When it's off, the card is hidden entirely rather than shown as a dead control.
• You are signed in as an Operator or Admin. Helpdesk and read-only users don't see it.

The card surfaces the screen-share-specific fields and one action:

Reading the last session#

The Last Session summary is drawn from the audit trail — specifically the record written when a screen-share session ends — so it reflects real activity and needs no separate storage. It includes:

If a machine has never had a screen-share session, the last-session fields are empty — which is itself a useful signal when a user reports “it never works” on a device you've actually never connected to.

The live relay test#

Screen-share connects direct-first over the local network; the TURN relay is an optional fallback for fully-remote NAT. The diagnostics relay test performs the same real check as the Test Relay button and the Settings → Test Connection probe: it makes a live TURN allocation against the configured relay using a freshly-minted credential, which validates in one shot that the relay is reachable, the shared secret matches, and a relay address can be allocated.

A quick troubleshooting flow#

When screen-share won't start for one machine, the diagnostics tell you where to look:

• Helper version is Not installed — the remote-helper isn't present or hasn't reported. Confirm the agent is up to date (see Agent Binaries & Updates).
• No last session, ever — nobody has successfully connected to this device; treat it as a first-time setup rather than a regression.
• Relay test fails (red) — if your environment relies on the relay, a secret mismatch or clock skew between the server and the relay host are the usual causes. See Verifying with Test Connection.
• Relay “not configured” (neutral) — expected on direct-first LANs; not a fault. If direct connections also fail, the problem is network reachability between operator and agent, not the relay.

REST API#

Diagnostics are available over the REST API as a single call. It requires the Operator or Admin role and returns 404 when the agent ID isn't found.

The live relay probe is controlled by a single query parameter:

# Full diagnostics including a live relay probe
GET /api/agents/550e8400-e29b-41d4-a716-446655440000/remote-diagnostics?includeRelayTest=true

# Fast read, no relay probe
GET /api/agents/550e8400-e29b-41d4-a716-446655440000/remote-diagnostics?includeRelayTest=false

The response body carries the fields described above:

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "webRtcEnabled": true,
  "helperVersion": "1.4.2",
  "agentVersion": "2.9.0",
  "currentUser": "athena",
  "lastSession": {
    "timestamp": "2026-07-17T14:03:11Z",
    "endReason": "operator-ended",
    "controlUsed": true
  },
  "relayReachability": {
    "success": true,
    "reachable": true,
    "authAccepted": true,
    "relayAddress": "100.93.42.87:49176",
    "latencyMs": 42,
    "message": "Relay reachable"
  }
}

PowerShell#

The Athena PowerShell module exposes diagnostics as a single cmdlet that accepts an agent from the pipeline, so you can pull it for one machine or fan it across a collection:

# Fast read for one agent (no relay probe)
Get-AthenaRemoteDiagnostics -AgentId "12345678-1234-1234-1234-123456789012"

# Include a live TURN relay-reachability probe
Get-AthenaRemoteDiagnostics -AgentId $agentId -IncludeRelayTest

# Pipe the target in from Get-AthenaAgent
Get-AthenaAgent -Hostname "server01" | Get-AthenaRemoteDiagnostics

See also#

• Remote Commands & Desktop — starting a screen-share session.
• Screen-Share Relay (TURN) — configuring and provisioning the optional media relay the test probes.
• Session Recordings — recorded remote sessions.
• Audit & SIEM — the session records the last-session summary is drawn from.