Which one to choose

	API token	Admin account
Credentials	Token ID (e.g. `verlocx@pve!portal`) + secret	User (e.g. `root@pam`) + password
How Verlocx signs in	Token on every request — nothing expires	Logs in like the web UI; the session is renewed automatically
Revoke without touching the user	Yes — delete the token	Only by changing the password
Two-factor on the account	Not affected	Not supported — use an account without 2FA, or a token
LVM snapshots (raw LVM storage)	Not available	Yes — the password is also used for SSH to the nodes
Everything else	Yes	Yes

Recommendation: use an API token. Use the admin account only if your VMs live on raw LVM storage and you want snapshots for them — Proxmox can't snapshot raw LVM through its API, so Verlocx does it over SSH.

Option A — API token

Create a dedicated user for Verlocx, give it administrator rights on the cluster, and create a token that inherits them (privilege separation off). On any node:

shell

1pveum user add verlocx@pve --comment "Verlocx portal"2pveum acl modify / --users verlocx@pve --roles Administrator3pveum user token add verlocx@pve portal --privsep 0

The last command prints the token's secret once — copy it. The token ID is verlocx@pve!portal. You can also create a token for root@pam in the web UI under Datacenter → Permissions → API Tokens; untick Privilege Separation so it has root's rights.

With privilege separation on, a token has no rights of its own until you grant them — Verlocx would connect, but every action would fail with “permission denied”.

Option B — Admin account

Use root@pam and its password, or another user in the pam realm with administrator rights and a matching Linux account on every node. The account must not require two-factor authentication.

Verlocx logs in to the API and renews its session in the background.
For VMs on raw LVM storage, Verlocx connects to the node over SSH (port 22) with the same user and password to create, merge and remove LVM snapshots.
All other storages (qcow2 directories, ZFS, Ceph RBD, LVM-thin) use Proxmox snapshots through the API — no SSH needed.

Add the cluster in Verlocx

Open Clusters and choose Add cluster.
Enter the API address of one node, e.g. https://pve01.example.com:8006. Add other nodes as fallback addresses — Verlocx switches over if the first is down.
Pick API token or Admin account and enter the credentials.
If the cluster uses its self-signed certificate, allow it (skip TLS verification) — or install a trusted certificate on the nodes.
Test the connection. Verlocx lists the nodes it found; save to finish.

Credentials are stored encrypted with VERLOCX_DB_ENCRYPTION_KEY and never sent to the browser.

What Verlocx does on the cluster

Area	Through
Clone templates, set CPU/RAM/disk, SMBIOS identity	API
Power: start, shutdown, reboot, stop, hibernate, resume	API
Proxmox snapshots and rollbacks	API
LVM snapshots on raw LVM	SSH (admin account only)
Backup jobs and restores	API
HA resources and node-affinity rules	API
Migration between nodes	API
Browser console (VNC)	API (console ticket)

Troubleshooting

Message	Usually means
“401 authentication failure”	Wrong token secret or password — or the admin account has two-factor authentication.
“403 permission denied” on actions	The token has privilege separation on, or the user lacks the Administrator role on /.
Connection test times out	Port `8006` blocked between the Verlocx server and the node — see Firewall & ports.
“needs SSH access” on a snapshot	The VM is on raw LVM storage and the cluster uses an API token — switch to the admin account for LVM snapshots.

Connecting Proxmox VE