Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt

Use this file to discover all available pages before exploring further.

When working with Windows machines over RDP, Remote Desktop, or virtualization software, you may encounter situations where the screen goes completely black due to session disconnection or display adapter issues. Black Screen Recovery automatically detects these situations and recovers the session by switching to the console session.

​
How it works

  • Periodic checks: Cyberdriver captures screenshots at regular intervals (default: 30 seconds)
  • Black screen detection: Uses variance analysis to detect truly black screens (variance < 1.0, mean pixel value < 10)
  • Confirmation check: When a black screen is detected, Cyberdriver waits 5 seconds and checks again to confirm it’s not a transient black screen (like during RDP connection)
  • Automatic recovery: If the black screen persists, executes a PowerShell script that runs tscon <session_id> /dest:console to switch the session back to the console
  • Initial check: Performs the first check 5 seconds after starting, regardless of the configured interval

​
Enable black screen recovery

cyberdriver join --secret YOUR_API_KEY --black-screen-recovery
Options:
  • --black-screen-recovery: Enables black screen detection and recovery
  • --black-screen-check-interval: Seconds between checks (default: 30)
Example with custom check interval: 
# Check every 60 seconds instead of 30
cyberdriver join --secret YOUR_API_KEY --black-screen-recovery \
  --black-screen-check-interval 60
Administrator Privileges RequiredThe console session switch (tscon) requires administrator privileges on Windows.Automatic Elevation (Recommended)When you run Cyberdriver with --black-screen-recovery, it will automatically check for administrator privileges:
cyberdriver join --secret YOUR_API_KEY --black-screen-recovery
  • If not running as admin: A UAC prompt will appear immediately, and Cyberdriver will restart itself with administrator privileges
  • If already admin: Cyberdriver will confirm and start normally
Alternative: Start from Administrator PowerShellFor automated/unattended environments, you can skip the UAC prompt by starting from an Administrator PowerShell:
  1. Right-click PowerShell and select “Run as Administrator”
  2. Then run cyberdriver join --secret YOUR_API_KEY --black-screen-recovery
  3. No UAC prompts will appear
If Elevation Fails or is CancelledIf you decline the UAC prompt or elevation fails, Cyberdriver will continue running but warn you that black screen recovery may not work. When a black screen is detected, another UAC prompt will appear at that time.

​
Manual recovery from the dashboard

If you want to switch back to the console session immediately, you can trigger the same recovery action from the Cyberdesk Dashboard:
  1. Open the desktop’s details page
  2. Click Tools
  3. Click Fix Black Screen
This runs the same tscon console-session switch through Cyberdesk’s PowerShell execution path, so it is a useful fallback if you do not want to wait for the next automatic check. If Cyberdriver is not already elevated, Windows may still show a UAC prompt before the session switch runs.
Black screen recovery works great alongside keepalive mode. Combine them for maximum uptime:
cyberdriver join --secret YOUR_API_KEY --keepalive --black-screen-recovery
This configuration keeps your session active during idle periods AND automatically recovers from black screen issues.

​
When to use this

Black Screen Recovery is particularly useful for:
  • RDP/Remote Desktop sessions that disconnect and show black screens
  • Virtual machines that lose display connectivity
  • Unattended automation where you need guaranteed screen availability
  • Long-running workflows that may experience session issues