// Help

Support

Stuck, found a bug, or want a feature? We are happy to help.

Email

For questions, problems and commercial licensing. We answer on Dutch business days, in English or Dutch.

GitHub issues

For bug reports and feature requests in public. Never post token secrets, and leave out hostnames and addresses.

When you report a problem, please include your VMherd version (ABOUT, top right in the app), your macOS version, your Proxmox VE version and what you expected to happen.

Quick troubleshooting

Where is the demo?

On the cluster screen, where your bookmarks are listed, click Try the demo. It opens a built-in demo cluster with simulated VMs: live consoles, power buttons and typing, all local on your Mac. No Proxmox server needed.

The VM list is empty, a console does not open, or power buttons fail

Check the permissions of your API token. VMherd needs VM.Audit to list VMs, VM.Console to open consoles and VM.PowerMgmt for start, shutdown and stop, on /vms or on a pool that holds your VMs.

Tokens created with privilege separation (the Proxmox default) do not inherit the user's permissions; give the token its own ACL:

On a Proxmox node

pveum acl modify /vms --tokens 'vmherd@pve!grid' --roles VMherd

The token ID in VMherd has the form user@realm!tokenname, for example vmherd@pve!grid.

If {{ipv4}} or {{ipv6}} types nothing for a VM: the QEMU guest agent must run in that VM, and the token needs VM.Monitor (Proxmox VE 8) or VM.GuestAgent.Audit (Proxmox VE 9). Containers need nothing extra.

VMherd cannot reach the server

The API URL must be HTTPS, usually https://pve.example.com:8006. Check that your Mac can reach that address and port (VPN, firewall). Plain http is only accepted for localhost.

"Certificate changed"

VMherd pins a server's certificate by its SHA-256 fingerprint the first time you connect, like SSH host keys. If the certificate changes later, VMherd refuses to connect until you trust it again.

If you renewed or replaced the certificate (a new ACME certificate, a reinstall, a new node), compare the fingerprint that VMherd shows with the one on the server: in the Proxmox web interface under node → System → Certificates, or on the node with openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256 (use pveproxy-ssl.pem instead if you installed a custom or ACME certificate). If they match, choose to trust it.
If you did not change anything, do not trust it: something between your Mac and the server may be intercepting the connection.

Wrong or missing characters with "Type text"

Broadcast and solo keystrokes are sent as physical keys, so the guest's own keyboard layout applies, like a real keyboard. Type text sends US key codes one character at a time, so for that the guest needs a US keyboard layout. If characters get lost, raise the per-character delay next to the TYPE button: QEMU's keyboard queue holds only a few keys.

My keys do not reach a console

For broadcast, the bar at the bottom must show ON AIR (click it, or press Enter when nothing else has the keyboard), and the tile's red sync toggle must be on.
For a single console, click inside it: it shows an amber SOLO label.
Keys only go out while the VMherd window is focused, and only to consoles that are connected.
Hold Esc for one second to leave broadcast or solo mode; a short Esc is sent to the consoles.

Using VMherd at work

The Mac App Store version is licensed under Apple's standard license agreement and covers use at work, on the Macs you own or control. See License.