Cyberdriver Installation - Cyberdesk Docs

What is Cyberdriver?

Cyberdriver is a small, simple executable that connects your desktop to Cyberdesk, enabling AI-powered automation of any desktop task. It provides a secure bridge between Cyberdesk’s cloud infrastructure and your local machine.

Key Features

Local HTTP Server - All endpoints for display, keyboard, and mouse control
WebSocket Tunnel - Secure connection to Cyberdesk cloud
Works on Physical & Virtual Machines - Run on your local Windows computer or any Windows VM
Console Protection - Prevents accidental termination by automated agents (Windows)
Keepalive Mode - Prevents idle timeouts and session locks
Black Screen Recovery - Automatically recovers from RDP display issues (Windows)
Persistent Virtual Display - Can start a virtual display that runs on console session

No Firewall Configuration Required

Unlike traditional remote desktop solutions, Cyberdriver doesn’t require you to open any inbound firewall ports. It works through a secure reverse tunnel, connecting outbound to Cyberdesk Cloud. This means:

✅ Works behind corporate firewalls
✅ No router configuration needed
✅ No exposed ports on your machine
✅ Secure, encrypted connection

Installation

Windows PowerShell Installation

The easiest way to install Cyberdriver on Windows is using our PowerShell installer.

Run the installer in PowerShell

# Create tool directory
$toolDir = "$env:USERPROFILE\.cyberdriver"
New-Item -ItemType Directory -Force -Path $toolDir

# Download cyberdriver
Invoke-WebRequest -Uri "https://github.com/cyberdesk-hq/cyberdriver/releases/download/v0.0.31/cyberdriver.exe" -OutFile "$toolDir\cyberdriver.exe"

# Add to PATH if not already there
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$toolDir*") {
    [Environment]::SetEnvironmentVariable("Path", $userPath + ";" + $toolDir, "User")
}

Write-Host "Cyberdriver installed! You may need to restart your terminal for PATH changes to take effect."

Restart PowerShell

Close and reopen your PowerShell terminal for the PATH changes to take effect. Once restarted, you’re ready to connect to Cyberdesk Cloud in the next section.

Cyberdriver automatically disables PowerShell’s QuickEdit Mode on startup. This prevents the terminal from freezing when you accidentally click on it while Cyberdriver is running.

Getting Started

Connect to Cyberdesk Cloud

To connect your desktop to Cyberdesk for remote automation:

cyberdriver join --secret YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key from the Cyberdesk Dashboard.

When you run cyberdriver join, Cyberdriver connects your machine to Cyberdesk Cloud using your API key. You can view the machine in the Cyberdesk Dashboard; the machine ID is managed in the backend and not printed by the CLI.

Common Issues

TLS Certificate Errors

If you encounter TLS certificate errors when connecting to Cyberdesk, run this PowerShell script to install the required certificates:

Fix TLS Certificate Errors

# Check if running as admin
$isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

if ($isAdmin) {
    $store = "Cert:\LocalMachine\Root"
    Write-Host "Running as Administrator - installing system-wide" -ForegroundColor Green
} else {
    $store = "Cert:\CurrentUser\Root"
    Write-Host "Running as user - installing for current user only" -ForegroundColor Yellow
}

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# Only the working certificate URLs
$certs = @(
    @{
        Name = "ISRG Root X1"
        Url = "https://letsencrypt.org/certs/isrgrootx1.der"
    }
)

foreach ($cert in $certs) {
    try {
        Write-Host "Downloading $($cert.Name)..." -ForegroundColor Cyan
        $tempFile = "$env:TEMP\$($cert.Name -replace ' ','_').der"
        Invoke-WebRequest -Uri $cert.Url -OutFile $tempFile -UseBasicParsing
        
        $certObj = Import-Certificate -FilePath $tempFile -CertStoreLocation $store
        Write-Host "✓ Installed $($cert.Name)" -ForegroundColor Green
        
        Remove-Item $tempFile -Force -ErrorAction SilentlyContinue
    } catch {
        Write-Host "✗ Failed to install $($cert.Name): $_" -ForegroundColor Red
    }
}

After running this script, retry the cyberdriver join command.

Cyberdriver Can’t Click or Interact with Certain Apps

If Cyberdriver appears to be running but can’t click on or interact with specific applications (especially legacy enterprise software or system utilities), this is typically a permissions issue. Solution: Run Cyberdriver from an Administrator PowerShell terminal:

Right-click on PowerShell and select “Run as Administrator”
Navigate to your desired directory
Run cyberdriver join --secret YOUR_API_KEY

Why this happens: Some desktop applications require admin privileges to receive input from other processes. While Cyberdriver doesn’t require administrator privileges by default, automating these admin-level applications requires Cyberdriver to run with elevated permissions.

For regular user-level applications, you can run Cyberdriver normally without admin privileges.

Connection Issues

If Cyberdriver fails to connect or keeps disconnecting:

Verify your API key - Make sure you’re using a valid API key from your dashboard
Check your internet connection - Cyberdriver requires a stable internet connection

Performance Issues

If automation seems slow or unresponsive:

Close unnecessary applications - Free up system resources
Check CPU usage - High CPU usage can affect automation performance
Disable Windows animations - This can speed up window switching

Keepalive Mode

Some desktop environments suspend or lock due to inactivity, which can stop active automation. Cyberdriver offers an optional keepalive mode to simulate light, realistic user activity when no work is incoming.

How it works

Idle detection: When connected via cyberdriver join, Cyberdriver tracks the last time it received a request from Cyberdesk Cloud.
Threshold: If there has been no work for a configurable threshold (default: 3 minutes), keepalive triggers.
Actions: Cyberdriver clicks near the bottom-left corner of the screen, types 2–5 short phrases with natural intervals, then presses Escape to close any UI. If your Windows Start icon isn’t in the bottom-left, you might not see anything visible, but the keepalive still works and prevents idle timeouts.
No disruption: If a request arrives while keepalive is running, Cyberdriver waits for keepalive to finish (to close Start/Spotlight cleanly) and then processes the request immediately. After any request, keepalive remains off until the system is idle again for the threshold.
Natural cadence: When remote keepalive activity is signaled from the host, the idle timer resets with a small random jitter (±7s) around your configured threshold.

Enable keepalive

cyberdriver join --secret YOUR_API_KEY --keepalive

Options:

--keepalive: Enables keepalive mode
--keepalive-threshold-minutes: Minutes of inactivity before keepalive runs (default: 3)
--keepalive-click-x and --keepalive-click-y: Custom click coordinates (default: bottom-left corner)

Example with custom click location:

# Click at coordinates (100, 100) instead of bottom-left
cyberdriver join --secret YOUR_API_KEY --keepalive \
  --keepalive-click-x 100 \
  --keepalive-click-y 100

Use custom click coordinates when your Start menu or application launcher is in a different location, or when you want the keepalive to interact with a specific area of the screen.

Keepalive uses a precise timer: when the configured idle threshold elapses with no work, the action starts immediately. After an action completes, the next eligible window is scheduled based on your threshold with a small random jitter (±7s or up to 20% of the threshold, whichever is smaller).

Disable/Re-enable without stopping the process

Start join in interactive mode to toggle the tunnel and keepalive on demand:

cyberdriver join --secret YOUR_API_KEY --keepalive --interactive

Inside the prompt:

d or disable: Disconnects the cloud tunnel and pauses keepalive. Local server stays up.
e or enable: Reconnects the tunnel and resumes keepalive.
q or quit: Exit cyberdriver.
h or help: Show commands.

Remote Keepalive (Host + VM)

When automating a Windows VM managed by remote desktop software (RDP, Avatara, AnyDesk, etc.), the VM often locks or shuts off after inactivity. Because this is enforced at the remote desktop layer, running keepalive inside the VM may not help. Remote Keepalive solves this by running a second Cyberdriver on the host (where the remote desktop software runs) to keep the VM session active while your main Cyberdriver inside the VM is idle. Why this matters: it keeps the VM ready for work without repeatedly passing 2FA every time you want to run a workflow. Quick setup (on the host machine):

cyberdriver join --secret YOUR_API_KEY --keepalive --register-as-keepalive-for <MAIN_MACHINE_ID>

What happens under the hood:

The host Cyberdriver links itself to your VM’s Cyberdriver (same organization enforced; self-links rejected).
The host Cyberdriver won’t interfere while a workflow runs on the VM. It only runs keepalive when the VM has been idle beyond your configured threshold.
If the VM’s own keepalive happens to be running when work arrives, Cyberdriver finishes that action before starting the workflow to avoid leaving UI elements open on the wrong screen.
Remote activity resets the VM’s idle timer with a small random jitter (±7s) around the keepalive threshold.
If the host Cyberdriver disconnects, the link is removed automatically. When it reconnects, the link is re-established.

Black Screen Recovery (Windows)

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:

Right-click PowerShell and select “Run as Administrator”
Then run cyberdriver join --secret YOUR_API_KEY --black-screen-recovery
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.

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

Persistent Virtual Display (Windows)

When you disconnect from an RDP session, Windows typically terminates the display, causing Cyberdriver to lose its ability to take screenshots and control the desktop. The Persistent Virtual Display feature solves this by installing a virtual display driver that remains active even when RDP is disconnected.

What it does

The --add-persistent-display flag automatically installs and configures the Amyuni USB Mobile Monitor virtual display driver, which:

Creates a virtual monitor that Windows treats as a real display
Persists across RDP disconnections, system reboots, and Cyberdriver restarts
Allows Cyberdriver to continue taking screenshots and controlling the desktop even when you’re not connected via RDP
Combines perfectly with Black Screen Recovery for ultimate RDP resilience

How it works

Automatic installation: Cyberdriver bundles the Amyuni driver files (adds only ~0.5 MB to the executable)
Smart detection: Checks if the driver is already installed to avoid redundant installations
One-time setup: Once installed, the virtual display persists permanently
Automatic enablement: Ensures the virtual display is enabled on every run

Enable persistent display

cyberdriver join --secret YOUR_API_KEY --add-persistent-display

Options:

--add-persistent-display: Installs and enables the virtual display driver (Windows only)

Combined with other features (recommended):

# Ultimate RDP-resistant setup
cyberdriver join --secret YOUR_API_KEY \
  --add-persistent-display \
  --black-screen-recovery \
  --keepalive

Administrator Privileges RequiredInstalling a display driver requires administrator privileges on Windows.Automatic ElevationWhen you run Cyberdriver with --add-persistent-display, it will automatically check for administrator privileges:

cyberdriver join --secret YOUR_API_KEY --add-persistent-display

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, install the driver (if needed), and start normally
If already installed: Cyberdriver will simply verify the display is enabled and continue

Alternative: Start from Administrator PowerShellFor automated/unattended environments, you can skip the UAC prompt by starting from an Administrator PowerShell:

Right-click PowerShell and select “Run as Administrator”
Then run cyberdriver join --secret YOUR_API_KEY --add-persistent-display
No UAC prompts will appear during installation

Configuring the virtual display

After the driver is installed, you can configure it like any physical monitor:

Open Windows Display Settings (right-click desktop → Display settings)
You’ll see a new monitor: “USB Mobile Monitor Virtual Display”
Configure as needed:
- Recommended resolution: 1024×768 (optimal for automation)
- Display mode: Extend or make it the primary display
- Position: Arrange relative to other displays

Pro tip: Set the virtual display as your primary monitor and configure it to 1024×768. This ensures Cyberdriver always has a consistent display to work with, regardless of RDP connection state.

How it works with RDP

Before (without persistent display):

Connect via RDP → Display available ✓
Disconnect RDP → Display terminated ✗
Cyberdriver can't take screenshots ✗
Automation stops working ✗

After (with persistent display):

Install virtual display (one-time setup)
Connect via RDP → Both displays available ✓
Disconnect RDP → Virtual display remains active ✓
Cyberdriver continues working normally ✓
Automation keeps running ✓

The ultimate RDP-resistant setup

Combine all three features for maximum reliability:

cyberdriver join --secret YOUR_API_KEY \
  --add-persistent-display \
  --black-screen-recovery \
  --keepalive

What you get:

✅ Persistent Display: Virtual monitor survives RDP disconnection
✅ Black Screen Recovery: Automatically fixes black screen issues
✅ Keepalive: Prevents idle timeouts and session locks
✅ Result: Cyberdriver stays alive and responsive 24/7, even through RDP disconnects

When to use this

Persistent Virtual Display is essential for:

RDP-based workflows where you need automation to continue after disconnecting
Unattended automation running on remote Windows machines
Long-running workflows that shouldn’t be interrupted by display issues
Production environments where reliability is critical

Removal (optional)

The virtual display persists even after Cyberdriver exits (by design). If you want to remove it: Option 1: Disable (keeps driver installed)

Open Windows Display Settings
Detect displays and disable the “USB Mobile Monitor Virtual Display”

Option 2: Uninstall completely

Open Device Manager (Win + X → Device Manager)
Expand “Monitors”
Right-click “USB Mobile Monitor Virtual Display”
Select “Uninstall device”
Check “Delete the driver software for this device”
Restart Windows

The virtual display is designed to persist across reboots. You typically want to keep it installed once set up, as it enables 24/7 automation without manual intervention.

Configuration

Cyberdriver stores its configuration in Windows at:

%LOCALAPPDATA%\.cyberdriver\config.json

The configuration file includes:

Version: Current Cyberdriver version
Fingerprint: Unique machine identifier
Connection settings: Host and authentication details

API Endpoints

Cyberdriver always starts a local HTTP server on port 3000. When you use cyberdriver join, it additionally creates a secure reverse tunnel to Cyberdesk Cloud, allowing remote access without opening any inbound ports. The local server exposes these endpoints:

Display

GET /computer/display/screenshot - Capture screen
- Query params: width, height, mode (exact/aspect_fit/aspect_fill)
- Returns: PNG image
GET /computer/display/dimensions - Get screen dimensions

Keyboard

POST /computer/input/keyboard/type - Type text
- Body: {"text": "Hello world"}
POST /computer/input/keyboard/key - Send key combinations
- Body: {"text": "ctrl+c"} (XDO style: ‘ctrl+c’, ‘alt+tab’, ‘cmd+a’)

Mouse

GET /computer/input/mouse/position - Get cursor position
POST /computer/input/mouse/move - Move cursor instantly
- Body: {"x": 100, "y": 200}
POST /computer/input/mouse/click - Click mouse button
- Body: {"button": "left", "down": true/false, "x": 100, "y": 200}
POST /computer/input/mouse/scroll - Scroll mouse wheel (vertical or horizontal)
- Body: {"direction": "up|down|left|right", "amount": 3, "x": 100, "y": 200}

File System

GET /computer/fs/list - List directory contents
- Query param: path (defaults to current directory)
GET /computer/fs/read - Read file contents
- Query param: path (required)
- Returns: Base64 encoded content (100MB limit)
POST /computer/fs/write - Write file contents
- Body: {"path": "/path/to/file", "content": "base64_encoded_data", "mode": "write/append"}

PowerShell

POST /computer/shell/powershell/exec - Execute PowerShell commands
- Body: {"command": "Get-Process", "timeout": 30, "working_directory": "C:\\"}
POST /computer/shell/powershell/session - Manage PowerShell sessions
- Body: {"action": "create/destroy", "session_id": "uuid"}

Utilities

Coordinate Capture

Need to find specific screen coordinates for keepalive configuration? Use the built-in coordinate capture tool:

cyberdriver coords

How to use:

Run the command in your terminal
Right-click anywhere on your screen (the Start button, Search icon, etc.)
The terminal will display the X,Y coordinates and a ready-to-use command
Press Esc to exit

Example output:

Right-click anywhere to capture coordinates. Press Esc to exit.

✓ Click captured: X=10, Y=1070

Use with keepalive:
  cyberdriver join --secret YOUR_KEY --keepalive \
    --keepalive-click-x 10 --keepalive-click-y 1070

You can right-click multiple times to try different locations. Each right-click will show you the coordinates and command.

Trackpad users: Right-click by using a two-finger click or tap on your trackpad. Regular left-clicks work normally and won’t be captured.

Console Protection (Windows)

When running cyberdriver join on Windows, Cyberdriver automatically protects its console window to prevent accidental termination by automated agents during workflows.

How it works

Close button disabled: The X button is grayed out and non-functional while Cyberdriver is running
Minimize/maximize preserved: These buttons remain fully functional - you can minimize or maximize the window normally
Safe shutdown: To stop Cyberdriver, use Ctrl+C in the console window - this restores the close button and exits cleanly

Why this matters

During automated workflows, AI agents can accidentally interact with visible console windows and close them, which would disconnect your machine and interrupt automation. Console protection ensures Cyberdriver stays running reliably even if agents try to close the window by clicking the X button.

Console protection is automatic and requires no configuration. It only activates when using cyberdriver join on Windows, and only protects Cyberdriver’s own console window - your other applications are unaffected.

Security Considerations

Cyberdriver provides remote access to your desktop. Follow these security best practices:

Keep your API key secret - Never share or commit it to version control
Use on trusted networks - Avoid public WiFi when possible
Monitor active connections - Check your dashboard for unexpected activity
Update regularly - Install Cyberdriver updates for security patches

Next Steps

Now that you have Cyberdriver installed and connected:

Quick Start Guide

Create and run your first workflow

SDK Guides

Learn how to trigger runs programmatically

Dashboard

Create workflows and manage machines

Support

Get help from the Cyberdesk team

Getting started

SDK Guides

Cyberdriver

Workflow Prompting

Webhooks

Concepts

​What is Cyberdriver?

​Key Features

​No Firewall Configuration Required

​Installation

​Windows PowerShell Installation

​Getting Started

​Connect to Cyberdesk Cloud

​Common Issues

​TLS Certificate Errors

​Cyberdriver Can’t Click or Interact with Certain Apps

​Connection Issues

​Performance Issues

​Keepalive Mode

​How it works

​Enable keepalive

​Disable/Re-enable without stopping the process

​Remote Keepalive (Host + VM)

​Black Screen Recovery (Windows)

​How it works

​Enable black screen recovery

​When to use this

​Persistent Virtual Display (Windows)

​What it does

​How it works

​Enable persistent display

​Configuring the virtual display

​How it works with RDP

​The ultimate RDP-resistant setup

​When to use this

​Removal (optional)

​Configuration

​API Endpoints

​Display

​Keyboard

​Mouse

​File System

​PowerShell

​Utilities

​Coordinate Capture

​Console Protection (Windows)

​How it works

​Why this matters

​Security Considerations

​Next Steps

Quick Start Guide

SDK Guides

Dashboard

Support

What is Cyberdriver?

Key Features

No Firewall Configuration Required

Installation

Windows PowerShell Installation

Getting Started

Connect to Cyberdesk Cloud

Common Issues

TLS Certificate Errors

Cyberdriver Can’t Click or Interact with Certain Apps

Connection Issues

Performance Issues

Keepalive Mode

How it works

Enable keepalive

Disable/Re-enable without stopping the process

Remote Keepalive (Host + VM)

Black Screen Recovery (Windows)

How it works

Enable black screen recovery

When to use this

Persistent Virtual Display (Windows)

What it does

How it works

Enable persistent display

Configuring the virtual display

How it works with RDP

The ultimate RDP-resistant setup

When to use this

Removal (optional)

Configuration

API Endpoints

Display

Keyboard

Mouse

File System

PowerShell

Utilities

Coordinate Capture

Console Protection (Windows)

How it works

Why this matters

Security Considerations

Next Steps