pve-agentsProxmox setup
Prepare Proxmox, a workspace network, and a reusable LXC template.
Complete this once before setting PROVISIONING_ENABLED=true. You can still try the controller
without Proxmox while provisioning remains off.
Create a workspace pool
pvesh create /pools --poolid disposable-workspacesSet PROXMOX_POOL if you choose another name. The pool is used to find workspaces and report
orphans; it does not by itself authorise deletion.
Create the API token
Create a dedicated Proxmox user and a privilege-separated API token. Scope it to the workspace pool,
clone storage, bridge or VNet, and the template. Do not grant permissions at /.
Set PROXMOX_URL, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET, PROXMOX_NODE, and PROXMOX_POOL.
The required privileges are listed in Credentials.
Prepare networking
Use a dedicated workspace VLAN or subnet with DHCP, outbound NAT, and no public inbound access. The controller must be able to reach port 22 on that subnet.
Set PROXMOX_BRIDGE, WORKSPACE_SUBNET, and PROXMOX_VMID_MIN. See
Networking for the recommended firewall policy.
Create the controller SSH key
Run this on the controller as its service account:
ssh-keygen -t ed25519 -N '' -C pve-agents-controller -f /var/lib/pve-agents/ssh/id_pve_agents_controller
chmod 0600 /var/lib/pve-agents/ssh/id_pve_agents_controllerSet WORKSPACE_SSH_KEY_PATH and WORKSPACE_SSH_USER=agent. Copy the public key to
/root/id_pve_agents_controller.pub on the Proxmox host before building the template.
Rotating this key requires a template rebuild. Existing workspaces continue using their installed public key.
Build the template
On the Proxmox host, download the base image for the first build:
pveam update
pveam download local ubuntu-24.04-standard_24.04-2_amd64.tar.zst
SOURCE_VMID= NEW_VMID=120 ./deploy/build-workspace-template.shFor later rebuilds, start from the template currently in service:
NEW_VMID=121 ./deploy/build-workspace-template.shThe script creates a new template; do not modify the source template in place. If validation fails, it retains the build container for inspection.
Enable provisioning
Set PROXMOX_TEMPLATE_VMID to the new VMID, then grant the API token VM.Audit and VM.Clone on
/vms/<vmid>. Add an agent in Settings → Agents, set PROVISIONING_ENABLED=true, and restart
the controller.
The controller requires CONTROLLER_AUTH_SECRET before it will start with provisioning enabled.
Continue with your first workspace.
Last updated on