Skip to content
Back to search

cv4pve-pepper

Open a Proxmox VE SPICE or VNC console from the command line

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Corsinvest/cv4pve-pepper with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Corsinvest/cv4pve-pepper'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/corsinvest--cv4pve-pepper/badge.svg)](/listings/corsinvest--cv4pve-pepper)

HTML

<a href="/listings/corsinvest--cv4pve-pepper"><img src="/api/listings/corsinvest--cv4pve-pepper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Windows
winget install Corsinvest.cv4pve.pepper
winget install RedHat.VirtViewer

# Linux (other platforms and packages: see the documentation)
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
sudo apt install virt-viewer

# Open the console of VM 100, with an API token
./cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=<uuid>' --vmid=100 --viewer=/usr/bin/remote-viewer

The API token needs `VM.Audit` and `VM.Console` on the guest, plus `VM.PowerMgmt` to start it: see [Permissions](https://corsinvest.github.io/cv4pve-pepper/permissions/).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 119 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # <img src="icon.png" alt="" height="36" align="top"> cv4pve-pepper
  2. ```
  3. ______ _ __
  4. / ____/___ __________(_)___ _ _____ _____/ /_
  5. / / / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
  6. / /___/ /_/ / / (__ ) / / / / |/ / __(__ ) /_
  7. \____/\____/_/ /____/_/_/ /_/|___/\___/____/\__/
  8. Launching SPICE/VNC Remote Viewer for Proxmox VE (Made in Italy)
  9. ```
  10. [![License](https://img.shields.io/github/license/Corsinvest/cv4pve-pepper.svg?style=flat-square)](LICENSE.md)
  11. [![Release](https://img.shields.io/github/release/Corsinvest/cv4pve-pepper.svg?style=flat-square)](https://github.com/Corsinvest/cv4pve-pepper/releases/latest)
  12. [![Downloads](https://img.shields.io/github/downloads/Corsinvest/cv4pve-pepper/total.svg?style=flat-square&logo=download)](https://github.com/Corsinvest/cv4pve-pepper/releases)
  13. [![WinGet](https://img.shields.io/winget/v/Corsinvest.cv4pve.pepper?style=flat-square&logo=windows)](https://winstall.app/apps/Corsinvest.cv4pve.pepper)
  14. [![AUR](https://img.shields.io/aur/version/cv4pve-pepper?style=flat-square&logo=archlinux)](https://aur.archlinux.org/packages/cv4pve-pepper)
  15. > **The console of any Proxmox VE VM, one command away**: SPICE or VNC, straight into `remote-viewer`, from your desktop, a script or a shortcut.
  16. >
  17. > **[Documentation](https://corsinvest.github.io/cv4pve-pepper/)**
  18. >
  19. > Prefer to pick your VMs from a list? [cv4pve-vdi](https://github.com/Corsinvest/cv4pve-vdi) is the desktop application built on the same console code.
  20. ---
  21. ## Why
  22. Opening a console in Proxmox VE means logging in to the web interface, finding the VM, clicking *Console*, or downloading a `.vv` file for SPICE and opening it before its ticket expires. Fine once; tedious when the same people open the same VMs every day, and impossible to put on a desktop icon.
  23. cv4pve-pepper does all of it in one command: it finds the VM or container by id or name, starts it if you ask, gets the console ticket and opens `remote-viewer`. Turn it into a desktop shortcut and a console is **one double-click away**, without giving anyone the web interface.
  24. It **runs on your computer and uses only the Proxmox VE API**: nothing to install on the cluster, no SSH.
  25. ---
  26. ## One command. Any VM. SPICE or VNC.
  27. ```bash
  28. # SPICE
  29. cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=<uuid>' --vmid=webserver --viewer=/usr/bin/remote-viewer
  30. # VNC: add --vnc
  31. cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=<uuid>' --vmid=webserver --viewer=/usr/bin/remote-viewer --vnc
  32. ```
  33. | SPICE | VNC |
  34. |---|---|
  35. | ![SPICE console opened by cv4pve-pepper](docs/src/assets/open-spice.png) | ![VNC console opened by cv4pve-pepper](docs/src/assets/open-vnc.png) |
  36. SPICE for the full desktop experience, VNC for every running VM and container: [which one to use](https://corsinvest.github.io/cv4pve-pepper/spice-and-vnc/).
  37. ---
  38. ## Features
  39. - **SPICE or VNC**: SPICE with audio, USB and clipboard when the VM is set up for it; VNC on every running VM and container, with no display setting to change.
  40. - **VNC through the API port**: the console travels inside the API connection on port 8006: nothing else to open in the firewall.
  41. - **By id or by name**: the same command keeps working when the VM migrates to another node.
  42. - **Starts it for you**: `--start-or-resume` starts a stopped guest or resumes a paused one, then opens the console.
  43. - **One icon per VM**: a parameter file and a desktop shortcut, on Windows and Linux; no console window on Windows.
  44. - **Keeps working with a node down**: give it more than one host and it uses the first that answers.
  45. - **Windows, Linux and macOS**: nothing else to install besides `remote-viewer`.
  46. ---
  47. ## Quick start
  48. ```bash
  49. # Windows
  50. winget install Corsinvest.cv4pve.pepper
  51. winget install RedHat.VirtViewer
  52. # Linux (other platforms and packages: see the documentation)
  53. wget https://github.com/Corsinvest/cv4pve-pepper/releases/latest/download/cv4pve-pepper-linux-x64.zip
  54. unzip cv4pve-pepper-linux-x64.zip && chmod +x cv4pve-pepper
  55. sudo apt install virt-viewer
  56. # Open the console of VM 100, with an API token
  57. ./cv4pve-pepper --host=pve01 --api-token='pepper@pve!console=<uuid>' --vmid=100 --viewer=/usr/bin/remote-viewer
  58. ```
  59. The API token needs `VM.Audit` and `VM.Console` on the guest, plus `VM.PowerMgmt` to start it: see [Permissions](https://corsinvest.github.io/cv4pve-pepper/permissions/).
  60. ---
  61. ## Documentation
  62. | | |
  63. |---|---|
  64. | [Getting started](https://corsinvest.github.io/cv4pve-pepper/getting-started/) | Install pepper and remote-viewer, connect, open a console |
  65. | [Permissions](https://corsinvest.github.io/cv4pve-pepper/permissions/) | The user, the API token and the privileges |
  66. | [Options](https://corsinvest.github.io/cv4pve-pepper/options/) | Every option: finding the VM, start or resume, the viewer |
  67. | [SPICE and VNC](https://corsinvest.github.io/cv4pve-pepper/spice-and-vnc/) | Which one to use, the SPICE proxy, how VNC travels through the API |
  68. | [Desktop shortcut](https://corsinvest.github.io/cv4pve-pepper/desktop-shortcut/) | Parameter file and one icon per VM on Windows and Linux |
  69. | [AI assistants](https://corsinvest.github.io/cv4pve-pepper/ai-agents/) | Claude Code, Codex, the `cv4pve-pepper` skill |
  70. | [Troubleshooting](https://corsinvest.github.io/cv4pve-pepper/troubleshooting/) | Error messages, scripts on Windows, debug output |
  71. ---
  72. ## Related tools
  73. Use `cv4pve-pepper` for one console on a command or an icon, [cv4pve-vdi](https://github.com/Corsinvest/cv4pve-vdi) to work on many VMs from a desktop application. The whole suite: [corsinvest.it/cv4pve](https://www.corsinvest.it/en/cv4pve/).
  74. ---
  75. ## Support
  76. Professional support and consulting available through [Corsinvest](https://www.corsinvest.it/en/cv4pve/).
  77. ---
  78. **By sysadmins, for sysadmins.**
  79. Part of [cv4pve](https://www.corsinvest.it/en/cv4pve/) suite | Made with ❤️ in Italy by [Corsinvest](https://www.corsinvest.it)
  80. Proxmox® is a registered trademark of Proxmox Server Solutions GmbH. cv4pve is developed by Corsinvest and is not a Proxmox product.
  81. Copyright © Corsinvest Srl

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.