Troubleshooting
A remote session will not open
Working through terminal and screen session failures, including the macOS permission trap.
Last updated
Remote sessions depend on three things being true simultaneously: the endpoint is online, the platform can issue a session ticket to your authenticated operator identity, and a WebSocket connection can be established between your browser and the platform. A failure in any of the three presents similarly, so check them in order.
First, confirm the endpoint is genuinely online right now rather than showing a state from a few minutes ago. A session cannot be opened to a machine that is not connected, and this accounts for a large share of reported session failures.
Second, confirm your session is properly authenticated. Session tickets are short-lived and issued to an authenticated operator. A console tab that has been open since yesterday may be presenting a session the platform no longer accepts, and the resulting failure looks like a product fault. Reload and sign in again before investigating further.
Third, consider the WebSocket path between your browser and the platform. Corporate proxies that inspect or restrict WebSocket traffic will let the console load perfectly and then block the session. The diagnostic that settles it in under a minute is to try from a different network — if it works from a mobile hotspot, the problem is your network, not the platform.
For screen sessions specifically on macOS, the overwhelmingly common cause is the Screen Recording privacy permission not having been granted to the agent. The session establishes and produces nothing useful, which reads as a bug and is not one. Grant the permission — ideally through a configuration profile deployed by your device-management platform rather than by asking a user to navigate system settings.
Bear in mind that screen access is a beta capability with incomplete multi-monitor handling. Behaviour on a machine with several displays may not match expectations, and that is a known limitation rather than an environmental problem to hunt down.
If a session opens and then drops repeatedly, look at the same middlebox timeout behaviour described under offline endpoints. Terminal sessions ride the same kind of long-lived connection and are affected by the same infrastructure.