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.

This page documents the legacy Python Cyberdriver (0.0.x). New installs should use Cyberdriver Quickstart. Keep this page for old customers, rollback situations, and one-off compatibility needs.

​
What is legacy Cyberdriver?

Legacy Cyberdriver is a small Python-based executable that connects your desktop to Cyberdesk, enabling AI-powered automation of desktop tasks. It provides a secure bridge between Cyberdesk’s cloud infrastructure and your local Windows machine.

​
Key features

  • Local HTTP server - Endpoints for display, keyboard, mouse, clipboard, file, and shell control.
  • WebSocket tunnel - Secure outbound connection to Cyberdesk Cloud.
  • Works on physical and virtual machines - Run on a local Windows computer or Windows VM.
  • Stealth mode - Runs invisibly in the background on Windows.
  • Keepalive mode - Prevents idle timeouts and session locks.
  • Black screen recovery - Automatically recovers from RDP display issues.
  • Persistent virtual display - Can start a virtual display that runs on the console session.
  • Remote updates - Update supported legacy versions from the dashboard.

​
No firewall configuration required

Legacy Cyberdriver does not require inbound firewall ports. It connects outbound to Cyberdesk Cloud through a secure reverse tunnel.
  • 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 legacy Cyberdriver on Windows is using the PowerShell installer.
1

Run the installer in PowerShell

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

# Download cyberdriver
try {
    Invoke-WebRequest -Uri "https://github.com/cyberdesk-hq/cyberdriver/releases/download/v0.0.44/cyberdriver.exe" -OutFile "$toolDir\cyberdriver.exe" -ErrorAction Stop
} catch {
    Write-Host "ERROR: Failed to download Cyberdriver. If Cyberdriver is already running, run 'cyberdriver stop' first. Otherwise, check your internet connection and try again." -ForegroundColor Red
    return
}

# Verify installation
if (Test-Path "$toolDir\cyberdriver.exe") {
    $fileSize = (Get-Item "$toolDir\cyberdriver.exe").Length
    if ($fileSize -gt 34MB) {
        # 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 successfully! You may need to restart your terminal for PATH changes to take effect."
    } else {
        Write-Host "ERROR: Download appears incomplete (file too small). Please try again." -ForegroundColor Red
    }
} else {
    Write-Host "ERROR: Download failed. Please try again." -ForegroundColor Red
}
2

Restart PowerShell

Close and reopen PowerShell for the PATH changes to take effect. Once restarted, you can connect to Cyberdesk Cloud.
Legacy Cyberdriver automatically disables PowerShell’s QuickEdit Mode on startup. This prevents the terminal from freezing if you accidentally click 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 API key from the Cyberdesk Dashboard. On Windows, legacy Cyberdriver runs in stealth mode by default, so cyberdriver join continues in the background with no visible window. You’ll see a confirmation message, then your PowerShell prompt returns immediately.

​
Stopping Cyberdriver

To stop Cyberdriver: 
cyberdriver stop
Since legacy Cyberdriver runs invisibly in the background, cyberdriver stop is the recommended way to shut it down. You can also end cyberdriver.exe in Task Manager.

​
Naming a machine at join time

Pass --name <value> to cyberdriver join to set a human-readable display name for the machine. The value lands on Machine.name in the dashboard and is searchable via the API. 
cyberdriver join --secret YOUR_API_KEY --name "i-0abc123def456"
Behavior:
  • First join (new fingerprint): the machine is created with name set to your value.
  • Subsequent joins (same fingerprint, different --name): the existing machine’s name is updated.
  • Subsequent joins without --name: the existing name is preserved.
  • Validation: printable ASCII only, max 128 characters, surrounding whitespace trimmed.
  • Uniqueness is not enforced. Two machines can share the same name.

​
Parallel provisioning recipe

When you boot many VMs from the same image, every fresh registration starts as name: null and the only differentiator is the Cyberdesk machine ID. Push a name you already know per VM and look it up afterwards.
1

Pick a unique name per VM

For example, use the cloud-provider instance ID, hostname, or workflow run ID.
cyberdriver join --secret "$CYBERDESK_API_KEY" --name "$INSTANCE_ID"
2

Look up the machine via API

curl -H "Authorization: Bearer $CYBERDESK_API_KEY" \
  "https://api.cyberdesk.io/v1/machines?name=$INSTANCE_ID"
The response is a paginated list. Pick a unique-per-VM string to make this a one-shot lookup.
3

Use the returned machine ID for runs

With the Cyberdesk-issued machine ID in hand, you can target the VM for workflow runs, proxy requests, and automation.

​
Common issues

​
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:
  1. Right-click PowerShell and select Run as Administrator.
  2. Navigate to your desired directory.
  3. Run cyberdriver join --secret YOUR_API_KEY.
Some desktop applications require admin privileges to receive input from other processes. For regular user-level applications, you can run Cyberdriver normally without admin privileges.

​
Connection issues

If Cyberdriver fails to connect or keeps disconnecting:
  1. Verify your API key.
  2. Check your internet connection.
  3. Run cyberdriver logs and contact support with the output.

​
Performance issues

If automation seems slow or unresponsive:
  1. Close unnecessary applications.
  2. Check CPU usage.
  3. Disable Windows animations to speed up window switching.

​
TLS certificate issues

Legacy Cyberdriver uses your system certificate store by default, which works automatically on most machines. It also bundles certifi as a fallback for machines missing standard root CAs. If you see TLS/SSL certificate errors:
  1. Corporate networks with SSL inspection should work if your IT department’s certificate is installed in the OS trust store.
  2. Fresh Windows machines may be missing root certificates. Install Windows updates or contact support if certifi fallback does not resolve it.

​
Space key not working in certain apps

Some applications, particularly legacy enterprise apps, may not respond correctly to space key input. Try the experimental space flag: 
cyberdriver join --secret YOUR_API_KEY --experimental-space
This sends space using a virtual key code (VK_SPACE) instead of the hardware scan code.

​
Failed to load Python DLL during start or reinstall

If you see an error like this: 
Failed to load Python DLL 'C:\Users\Administrator\AppData\Local\.cyberdriver\_pyinstaller\_MEI42282\python39.dll'.
LoadLibrary: The specified module could not be found.
The installation is likely corrupted. Fully remove all Cyberdriver remnants, reboot, then reinstall. Run in PowerShell: 
$ErrorActionPreference = "Stop"

# Stop running instances
try { cyberdriver stop --force --timeout 3 | Out-Null } catch {}
Get-Process cyberdriver -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue

# Stop updater/launcher leftovers if present
Get-CimInstance Win32_Process -ErrorAction SilentlyContinue |
  Where-Object { $_.CommandLine -match "cyberdriver-updater|cyberdriver-update\.exe|launch-hidden\.ps1|launch-hidden\.vbs" } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }

# Remove any leftover scheduled restart tasks from self-update
Get-ScheduledTask -TaskName "CyberdriverRestart_*" -ErrorAction SilentlyContinue |
  Unregister-ScheduledTask -Confirm:$false -ErrorAction SilentlyContinue

# Remove all known Cyberdriver folders
$paths = @(
  "$env:USERPROFILE\.cyberdriver",
  "$env:LOCALAPPDATA\.cyberdriver",
  "$env:APPDATA\.cyberdriver"
)
foreach ($p in $paths) {
  if (Test-Path $p) { Remove-Item $p -Recurse -Force -ErrorAction SilentlyContinue }
}

# Remove old PATH entry for clean reinstall
$toolDir = "$env:USERPROFILE\.cyberdriver"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath) {
  $newPath = (($userPath -split ';') | Where-Object { $_ -and ($_ -ne $toolDir) }) -join ';'
  [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
}

Write-Host "Cyberdriver cleanup complete. Reboot, then reinstall."

​
Configuration

Legacy Cyberdriver stores persistent configuration at:
  • %LOCALAPPDATA%\.cyberdriver\config.json
The configuration file includes:
  • Version: Current Cyberdriver version.
  • Fingerprint: Unique Cyberdesk machine identifier.
Connection details such as the current host, auth secret, and active tunnel state are runtime state, not fields stored in config.json.

​
API endpoints

When you run cyberdriver join, legacy Cyberdriver opens a local HTTP server on port 3000 by default. If that port is already in use, it falls forward to the next available local port. It also creates a secure reverse tunnel to Cyberdesk Cloud, allowing remote access without opening inbound ports.

​
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"}

​
Clipboard

  • POST /computer/copy_to_clipboard - Send Ctrl+C and return clipboard contents keyed by the requested name.
    • Body: {"text": "account_number"}

​
Mouse

  • GET /computer/input/mouse/position - Get cursor position.
  • POST /computer/input/mouse/move - Move cursor instantly.
  • POST /computer/input/mouse/click - Click mouse button.
  • POST /computer/input/mouse/drag - Drag from a start position to an end position.
  • POST /computer/input/mouse/scroll - Scroll mouse wheel vertically or horizontally.

​
File system

  • GET /computer/fs/list - List directory contents.
  • GET /computer/fs/read - Read file contents.
  • POST /computer/fs/write - Write file contents.

​
PowerShell

  • POST /computer/shell/powershell/exec - Execute PowerShell commands.
  • POST /computer/shell/powershell/session - Compatibility endpoint for create/destroy session IDs.

​
Security considerations

Legacy Cyberdriver provides remote access to your desktop. Keep your API key secret, use trusted machines, monitor dashboard activity, and update regularly for security fixes.

​
Legacy feature details

Legacy-specific features such as stealth mode, console protection, keepalive mode, black screen recovery, persistent virtual display, coordinate capture, and remote updates are kept here for compatibility. Some newer Cyberdriver docs describe the RustDesk-based 1.x client and may not apply to this Python executable. If you are intentionally running legacy Cyberdriver and need exact behavior for one of these features, contact the founders at founders@cyberdesk.io.

​
Next steps

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.