Connection & sessions

Connection error or session mismatch at run start

Connection errors and session mismatches happen when AgentOS and Desktop have lost sync, most often after a machine restart or sleep cycle.

Correct restart order for multi-machine setups:

1. Restart AgentOS on the target machine(s) first.
2. Then reconnect from AskUI Desktop.

If the error persists, use the Restart button on the Devices page in the Desktop sidebar to force a clean session reset. If the problem recurs after restarts, check whether the target machine received a new IP address from DHCP, see the entry below.

Tests won't start after a reboot or power outage

Work through this checklist:

1. Verify all services are running. Open the Devices page in AskUI Desktop and confirm every connected machine shows a green status.
2. Check for IP address changes. DHCP can reassign addresses after a restart, breaking a stored connection. Use hostnames instead of static IPs wherever possible.
3. Look for stale configuration. Old connection settings in your project or workspace config may point to a previous address. Update or remove them and re-add the device.

Run stops when RDP session is disconnected or screen is locked

• Remote Desktop (Windows), session disconnect: Disconnecting an RDP session suspends the virtual display. AgentOS in Host Mode loses its view of the screen and the run ends. Either keep the RDP session connected and the window visible during the run, or run AgentOS as a system service so it operates independently of the interactive session, see Running as a service.

• Remote Desktop (Windows), window minimized: Minimizing the RDP client window (mstsc) simulates a display disconnect on the remote machine. The Remote Device Controller loses access to the display and may return empty screenshots or shut down. To prevent this, set a registry value on the machine running the RDP client:

  Open regedit, navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Terminal Server Client, and create a DWORD value named RemoteDesktop_SuppressWhenMinimized with data 2.

• Locked screen: A locked session hides the display on both Windows and macOS. Either keep the machine unlocked during unattended runs, or use a virtual display tool that persists across lock events.

For fully unattended CI scenarios, the recommended setup is AgentOS as an OS service, see CI/CD integration.