Installation & Deployment

PVE VDI Client is built with Python 3 and relies on the virt-viewer application to render the remote desktop sessions. Because of this architecture, installation is a two-part process: installing the viewer dependency, and installing the client itself.

Core Dependency: `virt-viewer`

CRITICAL: You MUST install virt-viewer prior to using PVE VDI client.

PVE VDI Client does not implement the SPICE protocol itself. Instead, it handles authentication, API communication, and state management, and then securely pipes connection credentials to virt-viewer (or remote-viewer on Linux).

Installing virt-viewer

Windows: Download the MSI installer from the official Virtual Machine Manager site. For mass deployment, this MSI can be pushed via Active Directory Group Policy (GPO) or Endpoint Configuration Manager (SCCM).

Linux (Debian/Ubuntu):

sudo apt update && sudo apt install virt-viewer

Linux (RHEL/Fedora):
```
sudo dnf install virt-viewer
```

Installing PVE VDI Client on Windows

For Windows environments, the recommended deployment method is using the pre-compiled MSI packages.

Method 1: Using the Pre-built MSI (Recommended)

Navigate to the project's GitHub Releases page.
Download the latest .msi file.
Run the installer. It will install the application to %PROGRAMFILES%\VDIClient and create necessary Start Menu/Desktop shortcuts.

Best Practice for Enterprise: Deploy this MSI silently alongside the virt-viewer MSI using a deployment tool like PDQ Deploy, Intune, or SCCM.

Method 2: Running from Source

If you need to test modifications, debug, or prefer running raw Python, follow these steps. You must have Python 3.12 installed and added to your system PATH.

Clone the repository:

git clone https://github.com/joshpatten/PVE-VDIClient.git
cd PVE-VDIClient

Run the provided batch script to install dependencies:
```
requirements.bat
```
Note: This runs pip install for pyinstaller, proxmoxer, PySimpleGUI<5.0.0, requests, and pywin32.
Launch the client:
```
python vdiclient.py
```

Installing PVE VDI Client on Linux

On Linux, the client runs naturally as a Python script. We recommend cloning the repository and placing the script in a standard binary path.

Debian / Ubuntu

Run the following commands to install the prerequisites, clone the repository, and install the client executable system-wide:

# Install system dependencies
sudo apt update
sudo apt install python3-pip python3-tk virt-viewer git

# Clone the repository
git clone https://github.com/joshpatten/PVE-VDIClient.git
cd ./PVE-VDIClient/

# Install Python dependencies
chmod +x requirements.sh
./requirements.sh

# Make the client globally executable
sudo cp vdiclient.py /usr/local/bin/vdiclient
sudo chmod +x /usr/local/bin/vdiclient

Fedora / CentOS / RHEL

Run the following commands on a RedHat-based system. Note the package name differences (python3-tkinter instead of python3-tk).

# Install system dependencies
sudo dnf install python3-pip python3-tkinter virt-viewer git

# Clone the repository
git clone https://github.com/joshpatten/PVE-VDIClient.git
cd ./PVE-VDIClient/

# Install Python dependencies
chmod +x requirements.sh
./requirements.sh

# Make the client globally executable
sudo cp vdiclient.py /usr/local/bin/vdiclient
sudo chmod +x /usr/local/bin/vdiclient

Post-Installation Verification

To verify the installation was successful, simply run the client from your terminal or command prompt:

vdiclient --help

If the application prints the help menu and does not throw import errors, the environment is correctly set up. You must now configure the client before it can connect to Proxmox. Proceed to the Configuration guide.