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

# CLI and Machine Images

> Use Cyberdriver from the command line for AMIs, templates, and cloned fleets

The Cyberdriver CLI is useful when you bake a Windows AMI or golden template, then clone many VMs from it. The main rule is simple: install Cyberdriver in the image, but connect each cloned VM with its own API key and identity when it first boots.

## Install on Windows

Use the PowerShell installer script in [Cyberdriver Quickstart](/cyberdriver/quickstart#windows-install). That page is the source of truth for installing Cyberdriver, adding it to `PATH`, and verifying the CLI.

The current Windows installer requires Administrator because it installs Cyberdriver as a system service. You can run the Cyberdriver app as a normal user after installation, but a fully non-admin Windows install is not currently supported by the public Cyberdriver MSI.

## Common commands

After using the installer script above, restart PowerShell and `Cyberdriver.exe` should be available from any directory:

```powershell theme={null}
Cyberdriver.exe --version
Cyberdriver.exe status
Cyberdriver.exe config-print
Cyberdriver.exe logs --tail 65536
Cyberdriver.exe stop
```

`config-print` shows the current Cyberdesk environment, API base, Cyberdesk machine fingerprint, RustDesk peer ID, and whether the API key is configured.

For scripts, resolve the executable from `PATH` instead of assuming a drive letter:

```powershell theme={null}
$Cyberdriver = (Get-Command Cyberdriver.exe -ErrorAction Stop).Source
```

## Join Cyberdesk

Run this on the VM after it boots:

```powershell theme={null}
$Cyberdriver = (Get-Command Cyberdriver.exe -ErrorAction Stop).Source
& $Cyberdriver join --secret YOUR_API_KEY
```

For dev:

```powershell theme={null}
& $Cyberdriver join --secret YOUR_API_KEY --env dev
```

For a custom API host:

```powershell theme={null}
& $Cyberdriver join --secret YOUR_API_KEY --api-base wss://your-api.example.com
```

## Build an AMI or Image

<Steps>
  <Step title="Install Cyberdriver in the image">
    Install the Cyberdriver MSI while preparing your base Windows image.

    Do not join Cyberdesk in the base image unless you generate a new identity before each clone starts.
  </Step>

  <Step title="Add first-boot bootstrap">
    Configure your launch script, user data, or image init process to run:

    ```powershell theme={null}
    $Cyberdriver = (Get-Command Cyberdriver.exe -ErrorAction Stop).Source
    & $Cyberdriver join --secret $env:CYBERDESK_API_KEY --new-identity
    ```

    `--new-identity` resets both pieces of machine identity: the Cyberdesk fingerprint and the RustDesk peer ID/keypair. Use this for AMIs, templates, and cloned hosts. Reinstalling or updating Cyberdriver without this flag preserves identity.
  </Step>

  <Step title="Set a display name">
    Pass a name when the VM first joins:

    ```powershell theme={null}
    & $Cyberdriver join --secret $env:CYBERDESK_API_KEY --name "worker-$env:COMPUTERNAME"
    ```

    Names are optional but make large fleets much easier to manage.
  </Step>

  <Step title="Verify registration">
    After boot, check:

    ```powershell theme={null}
    & $Cyberdriver status
    & $Cyberdriver config-print
    ```

    Then confirm the desktop appears in the Cyberdesk dashboard.
  </Step>
</Steps>

## Remote keepalive from a host

If a host machine runs the remote desktop software for many VMs, you can register that host as the remote keepalive machine for a VM:

```powershell theme={null}
& $Cyberdriver join --secret YOUR_API_KEY --register-as-keepalive-for <MAIN_MACHINE_ID>
```

The same value can be configured in **Cyberdriver → Settings → Network → Remote keepalive for**.

See [Keepalive](/cyberdriver/keepalive) for the full host + VM explanation.

## Useful flags

| Flag                          | Use                                                                               |
| ----------------------------- | --------------------------------------------------------------------------------- |
| `--secret`                    | Cyberdesk organization API key.                                                   |
| `--name`                      | Optional dashboard display name.                                                  |
| `--new-identity`              | Generate a new Cyberdesk fingerprint and RustDesk peer ID/keypair before joining. |
| `--env dev`                   | Point Cyberdriver at Cyberdesk development.                                       |
| `--api-base`                  | Custom Cyberdesk tunnel API base.                                                 |
| `--register-as-keepalive-for` | Link this host as remote keepalive for a main machine ID.                         |

## Troubleshooting

If cloned VMs overwrite each other in the dashboard, the image was cloned with persisted identity. Run:

```powershell theme={null}
$Cyberdriver = (Get-Command Cyberdriver.exe -ErrorAction Stop).Source
& $Cyberdriver join --secret YOUR_API_KEY --new-identity
```

If the VM does not appear connected, check logs:

```powershell theme={null}
& $Cyberdriver logs --tail 65536
```

If you use a host-level remote keepalive Cyberdriver, make sure the host and VM API keys belong to the same Cyberdesk organization.