Configuration

PVE VDI Client requires a configuration file to function. Without it, the application does not know how to reach your Proxmox cluster. It uses a standard INI file format parsed by Python's configparser.

Configuration File Locations

The client automatically searches for a file named vdiclient.ini in the following locations, stopping at the first one it finds. You can override this behavior entirely using Command Line Options.

Windows Search Path:

%APPDATA%\VDIClient\vdiclient.ini (User-specific)
%PROGRAMFILES%\VDIClient\vdiclient.ini (System-wide 64-bit)
%PROGRAMFILES(x86)%\VDIClient\vdiclient.ini (System-wide 32-bit)
C:\Program Files\VDIClient\vdiclient.ini (Fallback)

Linux Search Path:

~/.config/VDIClient/vdiclient.ini (User-specific)
/etc/vdiclient/vdiclient.ini (System-wide)
/usr/local/etc/vdiclient/vdiclient.ini (System-wide local)

Section Breakdown

`[General]`

This section controls the overall appearance, behavior, and UI restrictions of the application.

Key	Type	Description	Default
`title`	String	The text displayed in the application window title bar.	`VDI Login`
`theme`	String	The PySimpleGUI theme. Run `vdiclient.py --list_themes` to view all.	`LightBlue`
`icon`	Filepath	Path to a `.ico` file for the window and taskbar icon.	None
`logo`	Filepath	Path to a `.png` file displayed prominently on the login and VM selection screens.	None
`kiosk`	Boolean	If `True`, removes the window title bar, forces the window on top, and prevents the user from closing the app natively.	`False`
`fullscreen`	Boolean	If `True`, launches `virt-viewer` in full-screen mode. Note: Overridden by kiosk mode.	`True`
`viewer_kiosk`	Boolean	If `True` (and `kiosk` is also `True`), passes kiosk arguments to `virt-viewer` preventing the user from closing the SPICE window.	`True`
`inidebug`	Boolean	Crucial for Troubleshooting. If `True`, displays the raw SPICE `.vv` configuration generated by Proxmox in a text window before launching the viewer.	`False`
`guest_type`	String	Filters the type of guests shown in the list. Valid options: `both`, `lxc`, `qemu`.	`both`
`show_reset`	Boolean	If `True`, adds a "Reset" button next to VMs allowing users to perform a hard ACPI reset.	`False`
`window_width`	Integer	Manually forces the window width in pixels.	Auto
`window_height`	Integer	Manually forces the window height in pixels.	Auto

`[Hosts.<GroupName>]`

This is where you define your Proxmox clusters. You can define multiple clusters by creating multiple sections (e.g., [Hosts.Production], [Hosts.Lab]). The <GroupName> portion is what is displayed to the user in the "Server Group" dropdown.

hostpool (Required JSON string): A JSON dictionary mapping Proxmox IP addresses or FQDNs to their API port (usually 8006). The client shuffles this list on connection to provide rudimentary load balancing and failover.
```
hostpool = {
               "10.10.10.100" : 8006,
               "pve1.example.com" : 8006
           }
```
Warning: INI parsers are sensitive to multiline values. Ensure all lines of the JSON dictionary are indented deeper than the hostpool = declaration.
auth_backend: The Proxmox authentication realm. Common values are pve (Proxmox built-in), pam (Linux system users), or custom LDAP/AD realms (e.g., ad-domain).
auth_totp (Boolean): Set to True if your Proxmox realm requires 2FA TOTP. This displays an additional "OTP Key" input field on the login screen.
tls_verify (Boolean): Set to False to ignore SSL certificate errors. Recommended to set to True in production with valid certificates.
user: Pre-fills the username field on the login screen.
token_name / token_value: Proxmox API token credentials. If these are provided alongside user, the client bypasses the password requirement. If only one cluster is defined, it will auto-login.
pwresetcmd: Full command-line string executed when the user clicks the "Password Reset" button. E.g., start chrome --app=https://selfservice.company.local.
auto_vmid (Integer): If specified, upon login, the client bypasses the VM selection screen and immediately attempts to connect to this VM ID.

`[SpiceProxyRedirect]`

The Problem: When you request a SPICE connection, Proxmox returns a configuration file containing a proxy address. Often, this is the internal hostname of the Proxmox node (e.g., pve1.local:3128). If your VDI clients are external or on a different subnet, they cannot resolve or route to pve1.local.

The Solution: This section allows you to rewrite those addresses on the fly before passing them to virt-viewer.

Format: Original_Proxy:Port = Desired_Proxy:Port

[SpiceProxyRedirect]
# Rewrite internal node names to a public IP/NAT address
pve1.local:3128 = 203.0.113.50:3128
pve2.local:3128 = 203.0.113.51:3128

Pro-tip: Enable inidebug = True in the [General] section to see exactly what proxy string Proxmox is returning if your connection is failing.

`[AdditionalParameters]`

Injects raw parameters directly into the SPICE configuration file passed to virt-viewer. This is used to enable advanced SPICE features like USB passthrough, smartcard sharing, or multiple monitors.

Refer to the remote-viewer manual for valid parameters.

[AdditionalParameters]
# Automatically redirect local USB devices to the VM
enable-usb-autoshare = true
# Enable multi-monitor support (if configured in PVE)
fullscreen = true

Comprehensive Example Configuration

[General]
title = Acme Corp Virtual Desktop
theme = DarkBlue3
icon = C:\Program Files\VDIClient\acme.ico
logo = C:\Program Files\VDIClient\acme_logo.png

# Lock down the UI for public lab computers
kiosk = True
viewer_kiosk = True
fullscreen = True

# Show QEMU VMs only, hide LXC containers
guest_type = qemu
show_reset = False

# --- Cluster 1: Production ---
[Hosts.Production]
hostpool = {
               "pve-01.acme.local" : 8006,
               "pve-02.acme.local" : 8006,
               "pve-03.acme.local" : 8006
           }
auth_backend = my-active-directory
auth_totp = false
tls_verify = true
pwresetcmd = start msedge https://passwordreset.acme.local

# --- Cluster 2: Legacy Apps (Auto-Login Example) ---
[Hosts.Legacy]
hostpool = {
               "legacy-pve.acme.local" : 8006
           }
auth_backend = pve
user = legacy_user
# Using Proxmox API Tokens for passwordless auth
token_name = vdi_token
token_value = 12345678-abcd-1234-abcd-1234567890ab
# Skip selection screen and jump straight into VM 105
auto_vmid = 105

[SpiceProxyRedirect]
# External NAT mapping
pve-01.acme.local:3128 = 198.51.100.10:3128

[AdditionalParameters]
# Pass local printers/USBs to the remote session
enable-usbredir = true