Quickstart: your first desktop pool

This walks you through the first end-to-end path in Planeon: connecting a Proxmox VE cluster, creating a pool of desktops from a template, granting a group access to it, and connecting from the browser as a user. Every step below happens in the web console once you're signed in as an administrator.

Prerequisites

• Planeon's control plane is installed and you can sign in as an administrator. See the installation guides if you haven't deployed it yet.
• A prepared VM template in Proxmox VE. The template needs the QEMU guest agent installed and a few other one-time steps done inside the guest before Planeon can clone and customize it reliably. See Preparing VM templates and come back here once you have one.

Add your Proxmox VE cluster

Open Settings → Proxmox Connection and select New cluster. Planeon connects to Proxmox VE the same way any Proxmox API client does — with a cluster name, the API endpoint, and an API token:

• Cluster name — a label for this cluster inside Planeon, for example Production PVE.
• PVE Host — your cluster's API endpoint, for example https://pve.example.local:8006.
• API token ID — an API token created in Proxmox VE, in the user@realm!tokenid form, for example root@pam!vdi-admin.
• API Token — the token secret Proxmox VE generated for that token.

Create the token in Proxmox VE's own Datacenter → Permissions → API Tokens screen first. Planeon verifies the token's effective privileges on the root path / when you test the connection, so either create the token with Privilege Separation disabled for a user that already holds these privileges, or create a role carrying the privileges below and grant it to the token on /:

Area	Privileges
System	Sys.Audit, Sys.Console, Sys.Modify, Sys.PowerMgmt, Sys.Syslog
Storage	Datastore.Audit, Datastore.Allocate, Datastore.AllocateSpace, Datastore.AllocateTemplate
Virtual machines	VM.Audit, VM.Allocate, VM.Backup, VM.Clone, VM.Config.CDROM, VM.Config.CPU, VM.Config.Cloudinit, VM.Config.Disk, VM.Config.HWType, VM.Config.Memory, VM.Config.Network, VM.Config.Options, VM.Console, VM.Migrate, VM.PowerMgmt, VM.Snapshot, VM.Snapshot.Rollback
Network (SDN)	SDN.Allocate, SDN.Audit, SDN.Use
Resource pools	Pool.Audit, Pool.Allocate
Access control	Group.Allocate, Permissions.Modify, Realm.Allocate, Realm.AllocateUser, User.Modify

Paste the token ID and secret into the cluster form. If your certificate is self-signed, also enable Skip TLS verification. Select Test Connection: it confirms Planeon can reach the cluster and checks every privilege in the table above, naming any that are missing so you can fix the role or token before continuing. Once the test passes, select Create cluster.

Wait for inventory sync

Once the cluster is connected, Planeon starts reading its nodes, storages, and VMs through the Proxmox API. This inventory refreshes automatically on a short cycle, so give it a few seconds and then open the VMs page — you should see your cluster's virtual machines listed, including the one you prepared as a template.

With inventory flowing, register that template as a platform template record: open Templates, select Register Existing, and pick your prepared VM from PVE template VM — only VMs that Proxmox VE itself already marks as templates appear in that list. The node and VMID are copied in automatically; give the record a Template Name (and optionally an OS type, description, and tags), then save. This creates a platform record pointing at the existing PVE template — it does not touch Proxmox VE itself.

Create your first desktop pool

Open Pools and select Create Pool. A pool describes the desired state of a group of desktops — Planeon keeps it filled to size by cloning and customizing VMs from your template. The fields that matter for a first pool:

• Pool Name — for example Windows 11 Standard.
• Template — the template record you just registered.
• Min Size / Max Size — the capacity range Planeon maintains for this pool.
• Warm Pool — how many desktops should be kept ready and waiting before anyone requests one.
• VM Naming Prefix — the prefix used for each cloned VM's name and guest hostname, for example win11-std becomes win11-std-1, win11-std-2, and so on.

Leave the placement, connection, and session policy sections at their defaults for now — you can revisit them later. Save the pool.

Watch your desktops provision

Open the new pool and select View VMs. Planeon's reconciliation loop notices the pool is below its target size and starts cloning and customizing VMs to fill it. Each managed VM's Lifecycle column moves through this sequence as it's built:

planned → cloning → cloned → customizing → ready

Behind customizing, Planeon is waiting for the guest agent to answer inside the freshly cloned VM, waiting out Windows setup on Windows guests, setting the guest hostname to match its prefix-N name, and running a health check — all before the VM counts as usable. A VM that reaches ready is warm-pool eligible and ready to be handed to a user; one that fails along the way shows failed with a reason such as an unreachable guest agent, so you know what to fix in the template. First-boot customization on a fresh Windows clone takes anywhere from several minutes up to tens of minutes — the readiness deadline defaults to 30 minutes — so a long wait here is normal and expected, not something to interrupt. If a VM instead sits stuck or shows failed, see Troubleshooting.

Grant a group access to the pool

Owning capacity isn't the same as being allowed to use it: a user or group needs an explicit entitlement before they can request a desktop from a pool. From the pool's row menu, select Entitlements, then Add entitlement and choose an existing group (or user) from your directory. Once added, every member of that group is entitled to request a desktop from this pool.

Connect from the user portal

Have an entitled user open the user portal in their browser and sign in through your identity provider. Once their desktop shows Ready to connect, they can select Connect in browser for a clientless session straight in the browser tab, or Download .rdp to open it with a native RDP client instead. That's the full path — from an empty cluster connection to a user on their desktop.

Where to next

From here:

• Manage running pools — capacity, placement, connection and session policy — from Desktop pools.
• Monitor live desktop sessions as users connect, disconnect, and reconnect from Sessions.
• Fine-tune who can reach which pools from Access management, alongside the rest of your users, groups, and roles.