Cyberdriver Installation

​

What is Cyberdriver?

​

Key Features

• Local HTTP Server - All endpoints for display, keyboard, and mouse control
• WebSocket Tunnel - Secure connection to Cyberdesk cloud
• Screenshot Capture - With intelligent scaling modes
• Advanced Keyboard Input - Support for complex key sequences
• Automatic Reconnection - Robust connection handling with exponential backoff

​

No Firewall Configuration Required

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

​

Installation

​

Windows PowerShell Installation

# 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.18/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."

​

Getting Started

​

Connect to Cyberdesk Cloud

cyberdriver join --secret YOUR_API_KEY

​

Local Development Mode

cyberdriver start

​

Keepalive Mode

​

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.
• 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 --keepalive-threshold-minutes 3

• --keepalive: Enables keepalive mode
• --keepalive-threshold-minutes: Minutes of inactivity before keepalive runs (default: 3)

​

Disable/Re-enable without stopping the process

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

• 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)

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

• 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.

​

Common Issues

​

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

​

Connection Issues

1. Verify your API key - Make sure you’re using a valid API key from your dashboard
2. Check your internet connection - Cyberdriver requires a stable internet connection
3. Check application permissions - If automating admin-level apps, ensure you’re running cyberdriver from an Administrator PowerShell terminal

​

Performance Issues

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

​

Configuration

• %LOCALAPPDATA%\.cyberdriver\config.json

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

​

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

​

Security Considerations

​

Next Steps