ADMINSeparate connection problems from task problems#
An Agent may be connected while a particular process or desktop task still fails. Work outward from the reported state: trust/connection, selected session, permission, task scope and final application effect. A successful heartbeat does not verify a whole desktop workflow.
When a task fails or becomes uncertain#
- Record the endpoint, requested operation and returned error/state.
- Check whether the intended user session and foreground application remain valid.
- Inspect execution status or the real computer before retrying an unknown outcome.
- Do not bypass session, frame or approval checks to make a failed operation proceed.
Online is a connection status#
The Agent sends heartbeat every 10 seconds. Core marks a connection stale after its 45-second heartbeat threshold; the client also detects receive silence at 45 seconds. Reconnect uses jittered exponential backoff capped at 60 seconds. Online does not prove an unlocked desktop, permitted tool, healthy model or completed job.
Start with the right evidence#
Use agent.list_endpoints and agent.get_status for an exact identity, then agent.list_sessions for available accounts/sessions. Review installation registration diagnostics on Core. Do not substitute AD enabled/disabled state for live Agent connectivity.
| Symptom | Diagnostic direction |
|---|---|
| Offline | Check authorized LAN/VPN reachability, Core HTTPS address/port, certificate SAN and enabled module |
| Enrollment rejected | Review campaign expiry/quota/revocation and signed identity; do not copy another endpoint’s credentials |
| TLS failure | Check the intended public CA and hostname; never disable verification or add an untrusted interception CA as a shortcut |
| USER_SESSION unavailable | Rediscover the exact active session/account; do not target a stale or guessed session |
| Frame expired/mismatched | Capture a fresh screen within the approved task; input uses a 30-second observation boundary |
| Foreground outside plan | Observe again and revise the approved executable/category scope if needed |
| Locked or secure desktop | Stop; the Agent does not bypass locks or UAC |
| Capture media unavailable | Recapture within scope; authenticated media slots expire and are consumed once |
| Task expired or exhausted | Request a revised bounded plan; approval is not a permanent desktop session |
| UNKNOWN execution | Inspect status and independent evidence; do not resend the original mutation blindly |
Offline enrollment and recovery#
The service-side bootstrap retries enrollment when Core returns. A package campaign can still expire before successful registration. Authorize recovery exists on Core and binds the original Agent identity/public key to a valid campaign. Do not re-pair, reinstall or copy secret stores merely to hide a diagnosis.
Output and cancellation#
Process outputs are bounded; returned truncation/drop markers matter. PowerShell uses a child-local UTF-8 stdout contract and separate stderr decoding; CMD/EXE use Windows OEM by default unless a supported encoding override is provided. Diagnostic output from a restarted journal is not a complete recovered execution transcript.
Stop/cancel controls the owned work; it does not promise to reverse an external effect already delivered. A network loss or deadline may leave an uncertain result. One Core ASGI worker is required by the in-memory connection hub.
Versions and checks after updating#
Check the actual Agent version and Online status after completion. Investigate an uncertain update result before repeating installation. Online and offline updates explains the current process. Tests of one installation do not establish large-fleet, every-application or full independent offline acceptance.
Installation · Tool reference · Security · General troubleshooting