Usage Guide

Once installed and configured, launching and using the PVE VDI Client is straightforward. This guide covers the operational workflow, necessary Proxmox permissions, and advanced command-line usage for dynamic environments.

Proxmox Permission Requirements

For a user to successfully authenticate and interact with a VM in the client, they must have appropriate roles assigned within Proxmox VE.

At a bare minimum, users require the following permissions assigned to the specific VMs/Pools they are intended to access:

Permission Why it is required by the VDI Client
VM.Audit Required to query the Proxmox API for the VM's existence, its name, and its current execution status (running, stopped).
VM.Console Required to request the temporary SPICE display ticket and connection parameters from the API.
VM.PowerMgmt Required because the client automatically attempts to start a stopped VM when the user clicks "Connect". (Also required if show_reset = True).

Best Practice: Create a custom Role in Proxmox (e.g., VDI_User) containing only these three permissions, and apply it to Users/Groups on specific VM Pools.

The End-User Workflow

  1. Launch: The user opens the application.
  2. Server Group (Optional): If multiple [Hosts.*] sections are defined in the config, the user selects their target environment from the dropdown.
  3. Authentication: The user enters their Proxmox username and password.
    • Note: The username must NOT include the realm (e.g., @pve or @pam). The client handles appending the realm based on the auth_backend configuration.
  4. Connecting: Upon clicking "Log In", the client connects to a random node in the hostpool. If a node is offline, it silently falls back to the next node.
  5. VM Selection: A list of permitted virtual desktops appears.
    • If a VM is running, the user can click Connect.
    • If a VM is stopped or suspended, clicking Connect will trigger a loading popup. The client sends a start/resume command to Proxmox and actively polls the backend task. Once the Proxmox task exits with an OK status, the SPICE connection is initiated.
  6. Remote Session: virt-viewer takes over the screen. Depending on kiosk/fullscreen settings, the user interacts with the remote OS until they shut it down or disconnect.

Command Line Options

While normal usage relies on the local vdiclient.ini file, several command-line arguments are available. These are exceptionally useful for scripts, shortcut modifications, or dynamic provisioning.

usage: vdiclient.py [-h] [--list_themes] [--config_type {file,http}] [--config_location CONFIG_LOCATION]
                    [--config_username CONFIG_USERNAME] [--config_password CONFIG_PASSWORD] [--ignore_ssl]

Proxmox VDI Client

options:
  -h, --help            show this help message and exit
  --list_themes         List all available PySimpleGUI themes
  --config_type {file,http}
                        Select config type (default: file)
  --config_location CONFIG_LOCATION
                        Specify the config location (default: search for config file)
  --config_username CONFIG_USERNAME
                        HTTP basic authentication username (default: None)
  --config_password CONFIG_PASSWORD
                        HTTP basic authentication password (default: None)
  --ignore_ssl          HTTPS ignore SSL certificate errors (default: False)

Advanced Scenario: HTTP Configuration Provisioning

Managing local .ini files across hundreds of distributed thin clients is tedious. A highly powerful feature of this client is its ability to fetch its configuration from a central web server on launch.

This ensures all endpoints instantly receive the latest cluster IPs, proxy redirect rules, and UI settings without needing local administrative access.

To use this, modify the target of your application shortcut to include the HTTP flags:

vdiclient.exe --config_type http --config_location "https://intranet.company.local/configs/vdiclient.ini"

Securing the Configuration: If your web server is protected by Basic Authentication (to prevent unauthorized users from viewing your cluster IPs), you can pass credentials seamlessly:

vdiclient.exe --config_type http \
              --config_location "https://secure.company.local/vdiclient.ini" \
              --config_username "vdi_fetcher" \
              --config_password "SuperSecretPassword" \
              --ignore_ssl
(Note: Always use HTTPS when transmitting Basic Auth credentials, even internally. The --ignore_ssl flag is available if your internal network relies on self-signed certificates).

Troubleshooting Common Issues

  • "Unable to connect to any VDI server"
    • Cause: The client cannot reach port 8006 on any IP listed in the hostpool.
    • Solution: Check local firewalls, VPN connections, and ensure the hostpool is formatted correctly in the config.
  • VM connects, but immediately closes / black screen.
    • Cause: This is almost always a SPICE proxy resolution issue.
    • Solution: Enable inidebug = True in vdiclient.ini. Try to connect again. A window will appear showing the SPICE config. Look at the proxy= line. Can your local computer ping or resolve that address? If not, you must configure the [SpiceProxyRedirect] section to translate it to a reachable IP.
  • "No desktop instances found"
    • Cause: Authentication succeeded, but Proxmox returned an empty list of VMs.
    • Solution: Verify the user has the VM.Audit permission on the VMs. Check if guest_type in the config is inadvertently filtering out the user's machines (e.g., set to lxc when they only have qemu machines).