Platforms and Nodes
Hypervisor endpoints, compute nodes, capacity, and overallocation
Platforms and nodes register your hypervisor infrastructure with NodeRings. A platform is the API endpoint your agent operator uses to manage VMs. A node is one host in that environment that can receive customer workloads.
Proxmox is supported today, select it as the driver when creating a platform. Other hypervisor types may be added over time; the driver tells NodeRings which API and operator to use.
You manage platforms and nodes at /infrastructure/platforms-nodes. Create a region and install an agent first. Each platform must be linked to a provisioned agent before orders can flow.
Platform
One platform represents one hypervisor API endpoint (a cluster or a single host).
| Field | What to enter |
|---|---|
| Name | Label for your dashboard (for example Frankfurt production) |
| Endpoint URL | Hypervisor API URL (for example https://pve.example.com:8006 on Proxmox), must match the endpoint configured on your agent |
| Driver | Hypervisor type, Proxmox is available today |
| Agent | The provisioned agent cluster that runs the operator for this endpoint |
Each endpoint URL can only be registered once per organization. NodeRings reports platform health from hypervisor metrics. The platform shows online when every host behind that endpoint is reachable.
Node
One node is one hypervisor host in the platform. The node name must exactly match the name shown in your hypervisor (on Proxmox, run pvesh get /nodes to list names).
| Field | What to enter |
|---|---|
| Node name | Exact host name from your hypervisor |
| Region | Customer-facing geography from Regions, must also appear on plans you sell |
| VM disk storage | Storage target for new VM disks (on Proxmox: storage ID such as local-lvm) |
| Backup storage | Storage target for VM backups (on Proxmox: storage ID such as local) |
| Backup compression | None, LZO, Gzip, or Zstd, on Proxmox, backups use snapshot mode so VMs stay running |
| VMID seed | Starting VM ID for customer VMs on this node |
| Maintenance mode | When on, NodeRings stops placing new VMs on this node |
The dashboard syncs CPU, memory, and storage inventory from your hypervisor. Confirm capacity bars populate after the agent and operator are running.
VM provisioning settings
Each node also carries VM provisioning settings that are applied to every customer VM created on it. Sensible defaults are pre-filled, so you only change these if your network layout requires it.
| Field | Default | What it controls |
|---|---|---|
| Network bridge | vmbr0 | Proxmox Linux bridge the VM's primary NIC attaches to (for example vmbr1 for a dedicated customer bridge) |
| Net device | net0 | Proxmox network device key used for the primary NIC |
| NIC model | virtio | Virtual NIC model (virtio, e1000, rtl8139, vmxnet3); keep virtio unless a guest OS needs otherwise |
| VLAN ID | 0 (untagged) | 802.1Q VLAN tag set on the primary NIC (Proxmox tag=); use 1–4094 to isolate customer traffic on a tagged VLAN |
| MAC prefix | BC:24:11 | First 3 octets used when NodeRings allocates a unique MAC address for each VM on this node |
| Proxmox CPU type | host | Guest CPU model (Proxmox cpu=); host gives best performance, x86-64-v2-AES/x86-64-v3 help live migration across mixed hardware |
MAC allocation: NodeRings assigns each VM a unique MAC address built from the node's MAC prefix plus a sequential suffix. The MAC is set on the Proxmox NIC and used by cloud-init to match the network interface inside the guest, so network configuration is reliable regardless of interface naming. Allocated MACs are visible per VM on the provider dashboard, and released for reuse when the VM is deleted.
Changes to these settings only affect newly created VMs; existing VMs keep the configuration they were provisioned with.
Resource overallocation
Each node has separate overallocation percentages for CPU, memory, and storage. Overallocation controls how much you can sell in total across all plans on a node, not how large a single plan can be.
Overallocation sets how much you can sell in total, not how large a single plan can be. A plan can never exceed a node's physical capacity.
On a node with 8 CPU, the largest plan you can sell is 8 vCPU: a 16 vCPU plan never passes, regardless of overallocation.
Overallocation sets how many vCPUs you can sell combined across active VMs. At 200% on that 8-core node, you can sell up to 16 vCPU in total, for example two 8 vCPU plans, but not one plan larger than 8 vCPU.
The same logic applies to memory. Raise overallocation only if you accept the operational risk of contention. Preflight Check enforces these limits before a plan can sell on a node.
Step-by-step
Create a platform
At /infrastructure/platforms-nodes, click Create platform and enter a name, endpoint URL, driver Proxmox, and your agent, then save.
The endpoint URL must match the hypervisor API URL configured when you set up the agent.
Add a node
Select the platform, click Add node, and enter the host name exactly as shown in your hypervisor, plus its region, storage targets, VMID seed, and overallocation defaults. Review the VM provisioning section (bridge, VLAN, MAC prefix, CPU type) if your network layout needs non-default values. Leave maintenance mode off unless you are draining the host.
Confirm inventory
Confirm the platform shows online and the node lists CPU, memory, and storage synced from your hypervisor. Then continue with IPAM, VM templates, and Plans & Addons.