If you run more than one Proxmox VE cluster — a production cluster at the office and a homelab cluster in the garage, or three separate three-node clusters spread across client sites — you already know the annoyance. Every cluster has its own web UI, its own login, its own bookmark. Moving a VM from one cluster to another means exporting, copying, and re-importing, because Proxmox VE's built-in live migration only works within a single cluster.
Proxmox Datacenter Manager (PDM) is Proxmox's answer to that problem: a separate, purpose-built product that sits above your existing PVE clusters and Proxmox Backup Server instances and gives you one dashboard, one login, and — critically — live migration of guests between independent clusters. It's not a replacement for clustering, and it doesn't merge your clusters into one. It's a management plane that talks to each cluster's API and stitches the results together.
This guide walks through installing PDM, connecting it to your existing Proxmox VE clusters with a properly scoped, least-privilege API token, and using it day to day — plus the handful of gotchas that trip people up the first time.
What You Will Learn
By the end of this article you'll know what Proxmox Datacenter Manager actually does and doesn't do, how to install it either from the official ISO or on top of an existing Debian system, how to set up a dedicated, restricted service account on each PVE cluster you want to manage (rather than handing PDM your root credentials), how to walk through the "Add Remote" wizard correctly the first time, and how to troubleshoot the connection and permission errors that most commonly show up during setup.
What Proxmox Datacenter Manager Actually Is
A Proxmox VE cluster is built on Corosync, which requires low-latency links between nodes and realistically tops out in the low tens of nodes before quorum management gets fragile. It was never designed to span sites or unify infrastructure that doesn't share a fast, reliable network. PDM works around that limitation by not clustering anything at all — it's a lightweight, standalone appliance that authenticates to each cluster's existing API using a token, the same way any external automation tool would.
Once you've added a cluster (Proxmox calls it a remote) to PDM, you get:
- A single dashboard listing every node, VM, and container across every connected cluster, with combined CPU, memory, and storage utilization graphs.
- Start, stop, shutdown, and reboot actions on guests, without switching web UIs.
- Live migration of a running VM from one independent cluster to another — the feature most people install PDM for.
- A consolidated Ceph dashboard when your remotes have Ceph configured, showing monitors, managers, OSDs, and pool health across clusters.
- Centralized visibility into connected Proxmox Backup Server instances alongside your PVE clusters.
What it is not: a replacement for Corosync clustering within a site, a way to share storage between clusters automatically, or a high-availability layer of its own. If PDM itself goes down, your individual PVE clusters keep running exactly as before — they simply lose the unified view until PDM comes back.
Before You Start
You'll need a dedicated machine or VM for PDM — it should not be installed on a node that is itself a member of one of the PVE clusters you intend to manage, since it's meant to be an independent control plane. Recommended specs for anything beyond a quick evaluation are a modern 64-bit CPU, at least 4 GiB of RAM, 40+ GB of free storage (hardware RAID with a battery-backed cache, or redundant ZFS), and a redundant network connection. For a lab evaluation, 1 core, 1 GiB of RAM, and 10 GB of disk will get the web UI up, though you'll want more headroom once you're managing several clusters at once.
You'll also need administrative access to each PVE cluster you plan to connect, since you're going to create a new user, role, and API token on each one before PDM ever sees it.
Step 1: Install Proxmox Datacenter Manager
There are two supported paths: the official bootable ISO, or installing the packages on top of an existing Debian 13 (Trixie) system. The ISO is the simpler route for a dedicated VM or bare-metal box, since it walks through disk partitioning, network configuration, and the root password interactively, the same way the Proxmox VE installer does. Grab it from the official downloads page and write it to a USB stick or attach it as a virtual CD-ROM to a new VM.
If you'd rather add PDM on top of a Debian install you already manage, add the appropriate repository and install the meta-package. First import the Proxmox release key:
wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
-O /usr/share/keyrings/proxmox-archive-keyring.gpgThen add the no-subscription repository (use the enterprise repository instead if you hold a subscription):
cat <<EOF > /etc/apt/sources.list.d/pdm.sources
Types: deb
URIs: http://download.proxmox.com/debian/pdm
Suites: trixie
Components: pdm-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOFUpdate and install. If you want PDM to also be able to run its own guests locally (uncommon — most people run it purely as a management appliance), install the full meta-package with the Proxmox kernel and ZFS support; otherwise the lighter container-only package is enough for a pure management install:
# Full install with Proxmox kernel + ZFS
apt update && apt install proxmox-datacenter-manager-meta
# Lightweight, management-only install
apt update && apt install proxmox-datacenter-manager-container-metaOnce installation finishes, the web interface is available on HTTPS port 8443 — note that this is different from Proxmox VE's port 8006, so both can happily run on the same LAN, or even the same box if you're just testing:
https://<pdm-ip-or-hostname>:8443Log in with the root credentials you set during installation. Like Proxmox VE, PDM ships with a self-signed certificate, so your browser will warn you on first connection — that's expected unless you've already replaced it with a certificate from your own CA or ACME.
Step 2: Create a Dedicated, Restricted User on Each PVE Cluster
It's tempting to just hand PDM a root API token and move on, but that means a compromised PDM instance has full control over every connected cluster. Instead, create a scoped-down service account on each PVE cluster you're going to connect, and do it before you touch the PDM UI at all.
On the Proxmox VE cluster, go to Datacenter → Users → Add and create a new user:
- User name: something identifiable, e.g.
pdm - Realm: Proxmox VE authentication server
- Password: a long random string — you'll authenticate with an API token, not this password, so generate something you'll never type and can forget
Next, build a role instead of relying on the built-in Administrator role. Go to Datacenter → Roles → Create, name it something like pdm-remote, and select the privileges PDM actually needs for what you want it to do. At minimum that means VM and storage audit privileges for dashboard visibility; add VM.PowerMgmt, VM.Migrate, and related privileges if you want to start/stop/migrate guests from PDM. Deliberately leave out privilege-escalation-adjacent rights such as User.Modify, Permissions.Modify, Mapping.Modify, and Sys.Modify — none of those are things PDM needs to do its job, and excluding them means a leaked token can't be used to create new admin users or rewrite cluster-wide settings.
Then assign the role: Datacenter → Permissions → Add → User Permission, with Path set to / (or a narrower path if you only want PDM to see specific pools or nodes), User set to the account you just created, Role set to your new custom role, and Propagate left checked so the permission cascades down to VMs and storage.
Step 3: Generate an API Token
Still on the PVE cluster, go to Datacenter → Permissions → API Tokens → Add. Choose your pdm user, give the token an ID such as pdm, and — this is the part people get wrong — uncheck "Privilege Separation." If privilege separation stays enabled, the token gets its own independent permission set that starts empty, and you'd have to duplicate every permission you just assigned to the user onto the token as well. Leaving it unchecked means the token simply inherits whatever the parent user can do, which is what you want here.
Copy the token secret the moment it's displayed — Proxmox shows it exactly once and never again. If you lose it, you'll need to revoke the token and generate a new one.
Step 4: Grab the Cluster's TLS Certificate Fingerprint
PDM verifies each remote's identity with its TLS certificate fingerprint rather than trusting whatever certificate is presented, so you'll need it for the next step. In the PVE web UI, select any node, go to System → Certificates, and open the pve-ssl.pem entry — the SHA-256 fingerprint is shown there. Copy it exactly, including the colons.
Step 5: Add the Cluster as a Remote in PDM
Back in the PDM web interface, go to Remotes → Add and step through the wizard:
- Connection details. Set the remote type to Proxmox VE, and enter the server address. Use the cluster's IP address rather than a DNS hostname where practical — if your DNS resolver has a bad day, you don't want PDM losing connectivity to every cluster at once over something unrelated to Proxmox itself. Paste in the certificate fingerprint from Step 4 and click Connect to confirm PDM can reach the API and the certificate matches.
- Authentication. Choose Use existing token rather than letting PDM try to generate one automatically — automatic token generation fails outright if the target user has two-factor authentication enabled, which is a common source of confusion during setup. Enter the token ID (
pdm@pve!pdm, following theuser@realm!tokennameformat) and the secret you copied earlier, then click Scan to confirm PDM can enumerate the cluster's nodes and guests with that token. - Endpoints. PDM auto-discovers every node in the cluster and lists them as endpoints. If it lists the same node more than once (this happens when a node has multiple reachable IPs), remove the duplicates and make sure the remaining entries use IP addresses rather than hostnames, for the same DNS-resilience reason as above.
- Finish. Complete the wizard. If the token's permissions are correct, the cluster's nodes and guests appear on the PDM dashboard within a few seconds. If they don't show up, or you see permission errors when trying to interact with a guest, double back to Step 2 and check the role assignment.
Repeat Steps 2 through 5 for every additional PVE cluster you want centrally managed. Proxmox Backup Server instances follow the same overall pattern — add a restricted user and API token on the PBS side, then add it in PDM as a Proxmox Backup Server remote instead of a PVE remote.
Migrating a VM Between Independent Clusters
This is the feature that usually justifies installing PDM in the first place. With two or more PVE remotes connected, select a running (or stopped) guest from the unified resource list, choose Migrate, and pick a target node on a different remote cluster. PDM orchestrates the transfer by streaming the VM's disks and, for a live migration, its memory state, over the network between the two clusters — there's no shared storage requirement, since the clusters are by definition independent. Migration speed is bound entirely by the network path between the two clusters, so a migration between two clusters on the same LAN behaves very differently than one crossing a WAN link; plan storage migrations of large disks accordingly, and consider doing them during a maintenance window if the link between sites is slow.
Access Control Inside PDM
PDM has its own, separate user and permission system from the PVE clusters it manages — logging into PDM doesn't automatically grant access to the underlying clusters, and vice versa. It supports five authentication realms: local Linux PAM accounts, its own internal pdm realm with a local password store, and external OpenID Connect, LDAP, or Active Directory servers for teams that want centralized login.
Unlike Proxmox VE, PDM does not currently support custom roles — you assign one of three built-in roles to a path: NoAccess (nothing permitted), Auditor (read-only visibility into status and configuration), and Administrator (full control over the assigned path). Permissions use the same filesystem-style path model as PVE, so you can, for example, grant a junior admin Auditor on / so they can see everything, while reserving Administrator on specific remotes for senior staff. If you need more granular splits than that, handle it at the PVE-remote-token level instead, since that's where custom roles are still available.
Troubleshooting Common Setup Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| "Connect" step fails with a certificate error | Fingerprint doesn't match, or was copied with missing/extra characters | Re-copy the fingerprint from Certificates → pve-ssl.pem on the target node, including every colon |
| Automatic token generation fails during the Authentication step | The target user has two-factor authentication enabled | Generate the token manually on the PVE side (Step 3) and select "Use existing token" instead |
| "Scan OK" succeeds but guests don't appear, or actions return permission errors | Privilege Separation was left enabled on the token, or the role is missing required privileges | Edit the token and uncheck Privilege Separation, or revisit the custom role and add the missing privilege (PDM's error messages usually name it) |
| Remote shows as unreachable intermittently | PDM was configured to use a DNS hostname that occasionally fails to resolve | Edit the remote's endpoints and switch to IP addresses |
| Duplicate node entries under one remote | A node is reachable on more than one network interface and PDM discovered both | Remove the duplicate endpoint during the Endpoints step, or afterward from Remotes → edit |
| Live migration between clusters is very slow | The network path between the two clusters is the bottleneck, not PDM | Check bandwidth between sites; consider scheduling large migrations for off-hours or over a dedicated link |
Security Notes
A few habits are worth locking in from day one rather than retrofitting later. Keep the per-cluster service account's role as narrow as the tasks you actually need PDM to perform — audit-only if you just want a dashboard, and add power-management or migration privileges only when you use those features. Never enable Privilege Separation and then skip assigning permissions to the token itself, since that silently leaves the token with no access at all and produces confusing "permission denied" errors that have nothing to do with the underlying user's rights. Treat the PDM host itself as a sensitive system — it holds valid API tokens for every cluster you've connected, so it deserves the same patching discipline, restricted network access, and backup coverage as your production PVE nodes, not the "it's just a dashboard" treatment.
Frequently Asked Questions
Does Proxmox Datacenter Manager replace Proxmox VE clustering?
No. Corosync-based clustering still governs shared configuration and quorum within a single cluster. PDM sits a layer above multiple independent clusters (each of which may or may not be internally clustered) and gives you a unified view and cross-cluster migration, without merging their configurations.
Can I manage a single standalone PVE node with PDM, or does it require a cluster?
Independent, non-clustered PVE nodes can be added as remotes too. PDM's "remote" concept covers both clustered and standalone Proxmox VE installations.
What happens to my clusters if the PDM server goes offline?
Nothing changes on the clusters themselves — they keep running and remain manageable through their own individual web UIs exactly as before. You only lose the unified dashboard and cross-cluster migration capability until PDM is back online.
Is a subscription required to install and use PDM?
No. The no-subscription repository used in this guide is free to use, the same way Proxmox VE's no-subscription repository is. A subscription unlocks the enterprise repository and official support, but isn't required to install or run PDM.
Can guests be migrated between clusters running different Proxmox VE versions?
PDM itself doesn't impose an artificial version match requirement, but as with any cross-cluster migration, compatibility depends on the underlying QEMU/LXC versions and guest configuration on both sides. Keeping connected clusters reasonably close in Proxmox VE version avoids most edge cases.
Why did I only get read-only access even though I set the role to Administrator in PDM?
PDM's own Administrator role controls what you can do inside the PDM interface, not what the underlying per-cluster API token is permitted to do on that cluster. If the token's PVE-side role is Auditor-equivalent, actions like power management or migration will fail regardless of your PDM-level role — check the token's permissions on the PVE cluster itself.
Wrapping Up
Proxmox Datacenter Manager doesn't try to be a second clustering layer or a storage-sharing tool — it's a focused control plane that gives you one login, one dashboard, and cross-cluster live migration over infrastructure that was never going to share a single Corosync cluster in the first place. The setup is mostly mechanical once you understand the shape of it: a scoped user and API token on each PVE cluster, a certificate fingerprint, and a short wizard in the PDM UI. Get the least-privilege role right the first time and the rest — adding more remotes, migrating guests between sites, keeping an eye on Ceph health across clusters — is just a matter of repeating the same handful of steps.