Getting started

cv4pve-pepper runs on the computer where the console should appear and talks only to the Proxmox VE REST API. Nothing is installed on the nodes.

Install cv4pve-pepper

Platform	How
Linux	wget https://github.com/Corsinvest/cv4pve-pepper/releases/latest/download/cv4pve-pepper-linux-x64.zip && unzip cv4pve-pepper-linux-x64.zip && chmod +x cv4pve-pepper ARM: cv4pve-pepper-linux-arm64.zip, cv4pve-pepper-linux-arm.zip
Debian / Ubuntu	sudo dpkg -i cv4pve-pepper-VERSION-ARCH.deb (amd64, arm64, armhf)
RHEL / Fedora	sudo rpm -i cv4pve-pepper-VERSION-ARCH.rpm (x86_64, aarch64, armv7hl)
Arch Linux	yay -S cv4pve-pepper
Windows (WinGet)	winget install Corsinvest.cv4pve.pepper
Windows (manual)	cv4pve-pepper.exe-win-x64.zip, also x86 and arm64
macOS (Homebrew)	brew install corsinvest/tap/cv4pve-pepper
macOS (installer)	cv4pve-pepper-VERSION-arm64.pkg (Apple silicon) or -x86_64.pkg (Intel)
macOS (manual)	cv4pve-pepper-osx-arm64.zip or cv4pve-pepper-osx-x64.zip

Binaries are self-contained: no .NET runtime to install. All files are on thelatest release page.

Install remote-viewer

pepper does not draw the console itself: it starts remote-viewer, the viewer of the virt-viewer project, and passes it the connection. Its path is the required --viewer option.

Only remote-viewer

The same viewer serves SPICE and VNC. VNC clients such as TigerVNC do not work: pepper passes the viewer a .vv connection file, which only remote-viewer reads.

Windows

winget install RedHat.VirtViewer

The viewer is C:\Program Files\VirtViewer v<version>\bin\remote-viewer.exe, e.g. VirtViewer v11.0-256. The installer is also on the SPICE download page.

Debian / Ubuntu

sudo apt install virt-viewer    # /usr/bin/remote-viewer

RHEL / Fedora

sudo dnf install virt-viewer    # /usr/bin/remote-viewer

macOS

See the SPICE macOS client page, then pass the path of remote-viewer to --viewer.

First run

Create a dedicated user and API token first — see Permissions. Then open the console of VM 100:

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

On Windows:

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

• Without other options pepper opens the SPICE console. A VM needs its display set to SPICE for that; containers always have it. For any other running VM add --vnc — see SPICE and VNC.
• --vmid takes the id or the name of the VM or container — see Options.
• If the guest is stopped, add --start-or-resume to start it first.

With SPICE pepper exits as soon as the viewer has started, and the viewer stays open. With --vnc pepper keeps running until you close the viewer, because it carries the console traffic.

Several nodes, username and password, certificates and options in a file: see Connection.

When the command works, put it in a parameter file and a desktop shortcut.