> ## 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.
# Cyberdriver Quickstart
> Install Cyberdriver and connect a desktop to Cyberdesk
Cyberdriver is the desktop companion app that connects a machine to Cyberdesk. For most new installs, start with **Legacy Cyberdriver**. It is the stable option for desktop automation when you do not need Windows login-screen access.
Use the [Cyberdriver 1.x beta](#beta-cyberdriver-1x-windows-install) only when you specifically need the newer Windows service path for boot-time startup or Windows login-screen control.
## Stable install: Legacy Cyberdriver
Legacy Cyberdriver is the default stable install path for desktop automation today. It does not require inbound firewall ports and works well for machines where a user session is already available.
Open PowerShell and run this installer script. It downloads legacy Cyberdriver `v0.0.41`, adds it to your user `PATH`, and verifies the download.
```powershell theme={null}
# 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.41/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
}
```
Close and reopen PowerShell, then join your machine with an organization API key from the Cyberdesk dashboard.
```bash theme={null}
cyberdriver join --secret YOUR_API_KEY
```
After the key is saved, the desktop should appear in **Cyberdesk -> Desktops**.
From the Cyberdesk dashboard, open the desktop and click the **Desktop Tools** button. Verify that it connects and you can control the computer.
Now that your desktop is connected, [create your first workflow and then create your first run](/quickstart). Let us know if you have any trouble.
For details and troubleshooting, see [Legacy Cyberdriver](/cyberdriver/legacy-cyberdriver).
## \[BETA] Cyberdriver 1.x Windows install
Cyberdriver 1.x beta is based on RustDesk and currently supported for Windows only. Use this beta path when you need Cyberdriver to run as a Windows service, start at boot, or control the Windows login screen.
Administrator is required for the current Windows installer because Cyberdriver installs a system service. After installation, users can open and use the Cyberdriver app normally; they do not need to run the app as Administrator day to day.
Open PowerShell as Administrator and run this beta installer script. It downloads Cyberdriver `1.0.2`, installs Cyberdriver as a Windows service, adds Cyberdriver to `PATH`, verifies the CLI, and opens Cyberdriver.
```powershell theme={null}
$ErrorActionPreference = "Stop"
$MsiUrl = "https://github.com/cyberdesk-hq/cyberdriver-new/releases/download/v1.0.2/Cyberdriver-1.0.2-windows-x64.msi"
$MsiPath = Join-Path $env:TEMP "Cyberdriver-1.0.2-windows-x64.msi"
$InstallDir = Join-Path $env:ProgramFiles "Cyberdriver"
$Cyberdriver = Join-Path $InstallDir "Cyberdriver.exe"
function Test-IsAdmin {
$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
$principal = New-Object Security.Principal.WindowsPrincipal($identity)
return $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
}
if (-not (Test-IsAdmin)) {
throw "Run PowerShell as Administrator, then rerun this installer."
}
try {
Write-Host "Downloading Cyberdriver..."
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri $MsiUrl -OutFile $MsiPath -UseBasicParsing
Write-Host "Installing Cyberdriver..."
$install = Start-Process msiexec.exe -ArgumentList @("/i", "`"$MsiPath`"", "/qn", "/norestart") -Wait -PassThru
if ($install.ExitCode -notin @(0, 3010)) {
throw "Cyberdriver MSI install failed with exit code $($install.ExitCode)."
}
if (-not (Test-Path $Cyberdriver)) {
throw "Cyberdriver.exe was not found at $Cyberdriver after install."
}
$machinePath = [Environment]::GetEnvironmentVariable("Path", "Machine")
$pathParts = @($machinePath -split ";" | Where-Object { $_ })
$alreadyOnPath = $pathParts | Where-Object { $_.TrimEnd("\") -ieq $InstallDir.TrimEnd("\") }
if (-not $alreadyOnPath) {
[Environment]::SetEnvironmentVariable("Path", (($pathParts + $InstallDir) -join ";"), "Machine")
}
if (($env:Path -split ";") -notcontains $InstallDir) {
$env:Path = "$env:Path;$InstallDir"
}
Write-Host "Verifying Cyberdriver CLI..."
& $Cyberdriver --version
Write-Host "Opening Cyberdriver..."
Start-Process -FilePath $Cyberdriver
Write-Host "Cyberdriver install complete. Restart PowerShell to pick up PATH in new shells."
} finally {
Remove-Item $MsiPath -ErrorAction SilentlyContinue
}
```
If Windows warns that the installer is not commonly downloaded, choose **More info**, then **Run anyway**. The beta MSI is not yet code-signed.
Open Cyberdriver from the Start menu. In the **Cyberdesk tunnel** card, paste an organization API key from the Cyberdesk dashboard and click **Save**.
After the key is saved, the desktop should appear in **Cyberdesk → Desktops**.
From the Cyberdesk dashboard, open the desktop and click the **Desktop Tools** button. Verify that it connects and you can control the computer. Cyberdriver will now persist on your machine, even across shutdowns.
Now that your desktop is connected, [create your first workflow and then create your first run](/quickstart). Let us know if you have any trouble.
### Why Administrator Is Required For The Beta MSI
The Cyberdriver 1.x beta Windows release is service-first. The MSI installs into `Program Files`, registers a Windows service, and adds Cyberdriver to the machine `PATH`, which requires Administrator.
This is what enables:
* Cyberdriver starting when the machine boots.
* Remote access before a user logs in.
* Windows login screen access.
* More reliable unattended automation after shutdowns and restarts.
A fully non-admin Windows setup is not supported by the current public MSI. Cyberdriver's upstream UI has a "Run without install" concept, but Cyberdesk does not currently ship or document a supported portable/non-admin Windows artifact. If we add one later, expect tradeoffs: it would only run while that user session is active, would not start at machine boot, would not control the Windows login screen, and may have weaker access to elevated/UAC contexts.
## Updating Cyberdriver 1.x beta
You can update Cyberdriver `1.0.0+` from the Cyberdesk dashboard without manually opening RDP as long as the existing Cyberdriver service is healthy enough for Cyberdesk to connect.
We are working on making this process even more seamless. For now, the dashboard update flow is the recommended way to update Cyberdriver `1.0.0+` without manually RDPing into the machine.
In the Cyberdesk dashboard, open the desktop and click **Desktop Tools**. For Cyberdriver `1.0.0+`, this opens the live Cyberdriver Web stream by default.
If an update is available, the right sidebar shows an **Update** button. Click it to start the guided update flow.
Cyberdesk blocks the update if the desktop currently has a running or scheduling run. If no run is active, confirm that no run is about to start on that desktop.
Cyberdesk runs the update through the existing Cyberdriver tunnel. If Windows shows an administrator prompt in the stream, approve it. The stream may briefly disconnect while the MSI updates or restarts the service.
Cyberdesk waits up to 5 minutes for Cyberdriver to reconnect and report the new version. If verification fails, reopen Desktop Tools after the desktop reconnects and try the update again.
## Troubleshooting
### Corporate TLS Inspection and Firewalls
Cyberdriver needs outbound access to Cyberdesk Cloud over HTTPS and secure WebSockets. Most enterprise networks work without inbound firewall changes because Cyberdriver initiates outbound connections, but corporate TLS inspection or strict proxy rules can still interrupt the tunnel.
Cyberdriver validates TLS certificates. Cyberdesk Cloud uses publicly trusted certificates, and Cyberdriver uses public CA roots plus the Windows certificate store when available. If a firewall or proxy intercepts TLS and re-signs Cyberdesk traffic with a private enterprise CA, Cyberdriver may reject the connection if that CA is not trusted by the service context.
Common symptoms include:
* Cyberdriver diagnostics show `api_key_configured = true`.
* The Cyberdriver service status is `ready`.
* The Cyberdesk tunnel stays in `reconnecting`.
* `last_error` mentions `invalid peer certificate: UnknownIssuer`.
The preferred enterprise setup is to bypass TLS inspection for Cyberdesk Cloud traffic, especially the long-lived WebSocket tunnel. If inspection is mandatory, deploy the organization's private root CA into the Windows trusted certificate store in a way that is available to the Cyberdriver Windows service. Installing a certificate only for the interactive user may not be enough.
Do not disable TLS verification for production. Any insecure or allow-insecure settings are intended only for localhost or development environments.
Firewall and proxy rules should also allow long-lived WebSocket connections and should not aggressively terminate idle WebSocket traffic.
Troubleshooting checklist:
1. Confirm the machine can reach Cyberdesk Cloud over HTTPS.
2. Confirm Cyberdesk WebSocket tunnel traffic is not blocked or intercepted.
3. Check whether the presented certificate issuer is a corporate proxy instead of a public CA.
4. If a corporate issuer is present, either bypass inspection for Cyberdesk or deploy the corporate root CA for the Cyberdriver service context.
5. Restart or reopen Cyberdriver and retry the connection.
For exact allowlist requirements in a locked-down enterprise network, reach out to the Cyberdesk founders and we can help review the deployment.
## What should happen after setup
Once connected:
* The machine appears online in the Cyberdesk dashboard.
* Other users in the same Cyberdesk organization can connect through Cyberdriver.
* RustDesk peer IDs stay under the hood; the UI shows Cyberdesk machine names and IDs.
* Desktop Tools can screenshot, click, type, scroll, use clipboard, access files, and run shell commands.
## Advanced topics
Use screenshots, mouse, keyboard, files, clipboard, and shell commands from Cyberdesk.
Collect logs and state when something goes wrong.
Keep idle machines lightly active during long-running operations.
Understand remote update and shutdown behavior.
How Cyberdriver handles RDP disconnects and virtual displays.
Route Cyberdriver through your own proxy domain.
Stable Python-based client for most installs.