Home
Softono
cv4pve-vdi

cv4pve-vdi

Open source MIT C#
Website GitHub
105
Stars
2
Forks
3
Issues
5
Watchers
2 weeks
Last Commit
Tunnel & Remote Access

About cv4pve-vdi

Desktop VDI client for Proxmox VE — SPICE, VNC, RDP and SSH console launchers

Platforms

Web Self-hosted Windows

Languages

C#

Links

Website Source Code
c
Published by
corsinvest
Visit View Profile

README.md

View on GitHub

cv4pve-vdi

   ______                _                      __
  / ____/___  __________(_)___ _   _____  _____/ /_
 / /   / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
/ /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_
\____/\____/_/  /____/_/_/ /_/|___/\___/____/\__/

VDI client for Proxmox VE (Made in Italy)

License Release Downloads

Overview

cv4pve-vdi is a desktop VDI client for Proxmox VE. It provides a graphical interface to browse, filter and connect to virtual machines and containers via SPICE, VNC and custom service launchers (RDP, SSH, and any other tool) — without opening the Proxmox web UI.

Theme light and dark

Login Card view List view
Login Card view List view

Quick Start

Download the latest release from the releases page, extract and run:

./cv4pve-vdi

Features

Core Capabilities

  • Card and list view — switch between a visual card layout and a compact list
  • SPICE console launch via remote-viewer
  • VNC console via internal WebSocket bridge — no firewall rules or node-side configuration required (see docs/BRIDGE-VNC.md)
  • Custom service launchers — RDP, SSH, PuTTY and any other tool (see docs/LAUNCHERS.md)
  • Per-VM services — multiple connections per VM with auto-discovery and RDP single sign-on (see docs/SERVICES.md)
  • Kiosk mode — lock down the application for thin-client and shared-workstation deployments (see docs/KIOSK.md)
  • Switch user — sign out and return to the login screen without restarting the app (from the More menu); confirms before closing any open viewer sessions
  • Open sessions panel — a strip at the top of the main window lists every running viewer (SPICE, VNC, RDP, SSH, custom launchers); click a session to bring its window back to the front, click ✕ to close it. Particularly useful in kiosk mode where the Windows taskbar is not available
  • VM/CT power control — Start and Shutdown buttons (with optional confirmation)
  • Real-time stats — CPU and RAM usage bars per VM
  • Auto-refresh every 30 seconds — toggle from the toolbar
  • Search bar — quick filter by name, ID, description or tag
  • Filter sidebar — filter by node, pool, status, type and tags
  • Tag support — color-coded badges with Proxmox VE tag colors
  • Multi-host — manage multiple Proxmox VE clusters from a single client
  • Theme support — Light and Dark themes
  • Multi-language — UI available in several languages, picked from the login window; contributions welcome (see docs/I18N.md)
  • Configurable — full settings UI for appearance, launchers, clusters and kiosk (see docs/SETTINGS.md)

VM Badges and Indicators

Each VM card and list row shows visual indicators:

Badge Description
🟢⚫ VM status: green = running, gray = stopped
🟢🔴⚫ QEMU guest agent status: green = running, red = not responding, gray = ping disabled or unknown
🔊 SPICE audio device configured
🔌 SPICE USB redirect configured
📋 SPICE clipboard sharing configured

Guest setup

A few features (SPICE audio/USB/clipboard, QEMU guest agent badge, auto-resolving the VM IP) require components installed inside the VM. See docs/GUEST-SETUP.md for the prerequisites.

[!NOTE] Only VMs and containers with actionable VDI capabilities are shown — running VMs with SPICE/VNC/services available, or stopped VMs configured for SPICE display (qxl/spice). SPICE and service checks run in parallel batches with caching to keep refreshes fast on large clusters.

Installation

Permissions Required
Permission Purpose
VM.Console Launch SPICE and VNC consoles
VM.PowerMgmt Start / Shutdown VMs
VM.Audit Read VM configuration and status
VM.Monitor QEMU guest agent interaction (agent ping, IP detection for services)
Sys.Console Launch node shell (SPICE)

Linux Installation

# Check available releases and get the specific version number
# Visit: https://github.com/Corsinvest/cv4pve-vdi/releases

# Download specific version (replace VERSION with actual version like v1.0.0)
wget https://github.com/Corsinvest/cv4pve-vdi/releases/download/VERSION/cv4pve-vdi-linux-x64.zip

# Alternative: Get latest release URL programmatically
LATEST_URL=$(curl -s https://api.github.com/repos/Corsinvest/cv4pve-vdi/releases/latest | grep browser_download_url | grep linux-x64 | cut -d '"' -f 4)
wget "$LATEST_URL"

# Extract and make executable
unzip cv4pve-vdi-linux-x64.zip
chmod +x cv4pve-vdi
./cv4pve-vdi

Windows Installation

Option 1: WinGet (Recommended)

# Install using Windows Package Manager
winget install Corsinvest.cv4pve.vdi

Option 2: Manual Installation

# Check available releases at: https://github.com/Corsinvest/cv4pve-vdi/releases
# Download specific version (replace VERSION with actual version)
Invoke-WebRequest -Uri "https://github.com/Corsinvest/cv4pve-vdi/releases/download/VERSION/cv4pve-vdi-win-x64.zip" -OutFile "cv4pve-vdi.zip"

# Extract
Expand-Archive cv4pve-vdi.zip -DestinationPath "C:\Tools\cv4pve-vdi"

macOS Installation

# Check available releases at: https://github.com/Corsinvest/cv4pve-vdi/releases
# Download specific version (replace VERSION with actual version)

# Apple Silicon (arm64)
wget https://github.com/Corsinvest/cv4pve-vdi/releases/download/VERSION/cv4pve-vdi-osx-arm64.zip
unzip cv4pve-vdi-osx-arm64.zip

# Intel (x64)
wget https://github.com/Corsinvest/cv4pve-vdi/releases/download/VERSION/cv4pve-vdi-osx-x64.zip
unzip cv4pve-vdi-osx-x64.zip

chmod +x cv4pve-vdi
./cv4pve-vdi

SPICE Client Setup

A SPICE viewer (remote-viewer) must be installed to use SPICE and VNC consoles.

Linux (Debian/Ubuntu) 
sudo apt-get install virt-viewer

Path: /usr/bin/remote-viewer

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

Path: /usr/bin/remote-viewer

Windows

Download from SPICE Space

Typical path: C:\Program Files\VirtViewer v?-???\bin\remote-viewer.exe

macOS

Download from SPICE Space macOS Client

Troubleshooting

VM not visible in the list

VMs are only shown if they have at least one actionable VDI capability:

  • Running VM with SPICE active
  • Running VM with at least one service configured
  • Stopped VM with SPICE display configured (qxl or spice in hardware settings)

Check the VM's display hardware in Proxmox VE → Hardware → Display → set to SPICE (qxl), or configure a service for the VM via Connect → Services....

SPICE launch fails
  • Verify the SPICE viewer path in Settings → Viewer
  • Ensure remote-viewer is installed
  • Check that the VM display is set to SPICE (qxl) in Proxmox VE hardware settings
Connect button has no items

The Connect dropdown shows SPICE, VNC and any configured services. If it appears empty:

  • Ensure SPICE or VNC are enabled in Settings → Viewer
  • Configure services for the VM via Connect → Services...
Service not launching (RDP, SSH, etc.)
  • Verify the launcher executable path is correct and the tool is installed
  • Ensure the VM's guest agent is active so its IP can be resolved, or set an IP override in the service configuration
  • Check that the port is reachable from your machine
Agent badge not showing or always gray
  • The agent badge is only visible on QEMU VMs (not LXC containers)
  • The badge is shown if the agent is configured in Proxmox VE VM Options, but stays gray until Ping guest agent is enabled in Settings → Viewer
  • Enable Ping guest agent (QEMU only) in Settings → Viewer to get live green/red status
  • Ensure qemu-guest-agent is installed and running inside the VM
SPICE audio / clipboard / USB redirect not working

These features require:

  1. VM display set to SPICE in Proxmox VE → Hardware → Display
  2. Windows: install SPICE Guest Tools
  3. Linux: install spice-vdagent and spice-webdavd

The badges (audio/USB/clipboard icons) appear on the VM card only if the corresponding hardware is configured in Proxmox VE.

Support

Professional support and consulting available through Corsinvest.

If you prefer working from the terminal, check out cv4pve-pepper — the command-line companion for launching SPICE consoles on Proxmox VE.

Part of cv4pve suite | Made with ❤️ in Italy by Corsinvest

Copyright © Corsinvest Srl