The console of any Proxmox VE VM, one command away

Runs outside the nodes, API only. cv4pve-pepper finds the VM or container by id or name, starts it if you ask, and opens its SPICE or VNC console in remote-viewer, with no web interface and no .vv file to download.

Get started SPICE or VNC?

By sysadmins, for sysadmins.

Built by Corsinvest, official Proxmox partner.

arch=$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/;s/armv7l/arm/')
wget https://github.com/Corsinvest/cv4pve-pepper/releases/latest/download/cv4pve-pepper-linux-$arch.zip
unzip cv4pve-pepper-linux-$arch.zip
chmod +x cv4pve-pepper

curl -s https://api.github.com/repos/Corsinvest/cv4pve-pepper/releases/latest | grep -o "https://[^\"]*-$(dpkg --print-architecture)\.deb" | xargs curl -LO
sudo dpkg -i cv4pve-pepper-*-$(dpkg --print-architecture).deb

curl -s https://api.github.com/repos/Corsinvest/cv4pve-pepper/releases/latest | grep -o "https://[^\"]*-$(rpm --eval %_target_cpu)\.rpm" | xargs curl -LO
sudo rpm -i cv4pve-pepper-*-$(rpm --eval %_target_cpu).rpm

yay -S cv4pve-pepper

brew install corsinvest/tap/cv4pve-pepper

curl -s https://api.github.com/repos/Corsinvest/cv4pve-pepper/releases/latest | grep -o "https://[^\"]*-$(uname -m)\.pkg" | xargs curl -LO
sudo installer -target / -pkg cv4pve-pepper-*-$(uname -m).pkg

arch=$(uname -m | sed 's/x86_64/x64/')
curl -LO https://github.com/Corsinvest/cv4pve-pepper/releases/latest/download/cv4pve-pepper-osx-$arch.zip
unzip cv4pve-pepper-osx-$arch.zip
chmod +x cv4pve-pepper

WinGet
zip

winget install Corsinvest.cv4pve.pepper

$arch = @{ AMD64 = 'x64'; x86 = 'x86'; ARM64 = 'arm64' }[$env:PROCESSOR_ARCHITECTURE]
Invoke-WebRequest https://github.com/Corsinvest/cv4pve-pepper/releases/latest/download/cv4pve-pepper.exe-win-$arch.zip -OutFile cv4pve-pepper.zip
Expand-Archive cv4pve-pepper.zip -DestinationPath . -Force

All files are on the latest release page.

pepper shows the console in remote-viewer: install it too, then open the console of VM 100.

sudo apt install virt-viewer    # Debian / Ubuntu; other systems: see Getting started

cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=…' --vmid=100 \
  --viewer=/usr/bin/remote-viewer

# remote-viewer: see Getting started
cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=…' --vmid=100 \
  --viewer=/path/to/remote-viewer

winget install RedHat.VirtViewer

cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=…' --vmid=100 `
  --viewer="C:\Program Files\VirtViewer v11.0-256\bin\remote-viewer.exe"

Why

In Proxmox VE the console of a VM is a few clicks away in the web interface: log in, find the VM, open Console, or download a .vv file for SPICE and open it before its ticket expires. That is fine once. It is not when the same people open the same VMs every day, when a script has to show a console, or when a user should only get an icon on the desktop, not the whole web interface.

cv4pve-pepper does those steps in one command. It asks the API for a console ticket, writes the file for the viewer and starts remote-viewer with it, so the console can be a shortcut, a line in a script or a menu entry.

One command. Any VM. SPICE or VNC.

SPICE for the full desktop experience, VNC for every running VM and container: switch with a single flag.

SPICE
VNC

cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=…' --vmid=webserver --viewer=/usr/bin/remote-viewer

remote-viewer showing the SPICE console of container 105, at the login prompt

cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=…' --vmid=webserver --viewer=/usr/bin/remote-viewer --vnc

remote-viewer titled VNC: CT 105, showing the VNC console of container 105 at the login prompt

pepper connects to pve01 and looks up webserver in the cluster, on whichever node it runs.
For SPICE it asks Proxmox VE for a SPICE ticket and writes a .vv file in the temporary folder; for VNC (--vnc) it opens a local bridge to the console.
It starts remote-viewer, which opens the console window and deletes the .vv file once read.
With SPICE pepper exits at once and the viewer stays open; with VNC pepper keeps the bridge open until you close the viewer.

Where it fits

cv4pve-pepper opens one console, from the command line. Its companion cv4pve-vdi is the desktop application for people who pick their VM from a list. Both use the same console code, so SPICE and VNC behave the same way.

	cv4pve-pepper	cv4pve-vdi
What it is	Command-line tool	Desktop application
You choose the VM	On the command line or in a parameter file	From the list of the VMs you may use
Consoles	SPICE, VNC	SPICE, VNC, plus RDP, SSH and custom services
Login	API token or user and password, in options or a file	User and password, per person
Best for	Shortcuts, scripts, one console per icon	Users working on several VMs every day
Access	Proxmox VE API only, from outside the nodes	Proxmox VE API only, from outside the nodes

Outside the nodes, API only

cv4pve-pepper runs on the computer where the console should appear and talks only to the Proxmox VE REST API on port 8006, plus the SPICE proxy on port 3128 for SPICE. Nothing is installed on the nodes and no SSH is needed: an account with the privileges in Permissions is enough. Give it more than one node and it connects to the first one that answers.