How registration works
Phases, checkpoints, and what nr cluster register installs on your agent VM
nr cluster register is an orchestrator. It creates an agent in the NodeRings API, installs a small Kubernetes cluster on your VM, peers it to NodeRings, and optionally installs a hypervisor operator and, with --pterodactyl, the game server operator.
Phase overview
| Order | Phase | What happens |
|---|---|---|
| 1 | Agent record | Create or reuse agent (--name / --agent-id) |
| 2 | Prechecks | OS, ports, disk, memory (unless --skip-prechecks) |
| 3 | k3s | Lightweight Kubernetes on the VM |
| 4 | Calico | CNI replacing the default flannel path |
| 5 | Liqo | Install Liqo for Kubernetes-native peering |
| 6 | Outbound peer | Provider initiates peering toward NodeRings |
| 7 | Offloading | Offload VNC gateway (and optional) namespaces |
| 8 | Inbound peering | Complete the bidirectional peering handshake |
| 9 | Operator (optional) | Helm install of the hypervisor operator. With --pterodactyl, also the game server operator. Panel URL, keys, and user id are prompted unless flags or PTERODACTYL_* are set. |
| 10 | Verify | Pass/fail health gate |
Exact names in local state may differ slightly; nr cluster status shows where you are.
Version pins
Before installing components, the CLI asks the API for platform-pinned versions (k3s, Calico, Liqo, helm, liqoctl, and related tools). That keeps providers on combinations NodeRings has validated.
--offline skips the pin fetch and falls back to local config defaults — use only for constrained experiments.
Companion tools
Missing helm / liqoctl binaries are installed into ~/.nr/bin with checksum verification when the platform provides digests. Keep ~/.nr/bin on your PATH for later liqoctl use.
Operator boundary
The hypervisor operator phase is optional at the CLI level (--skip-operator-install) but required before you can sell VMs. Hypervisor credentials and Pterodactyl panel keys never leave your cluster: the CLI creates Kubernetes Secrets locally; NodeRings only sends Custom Resources into permissioned namespaces.
Resume semantics
Each successful phase writes a checkpoint. --resume continues from the last success instead of redoing completed work. See Local state and Resume & recover.
What NodeRings can and cannot do
| NodeRings can | NodeRings cannot |
|---|---|
| Send VM orders as CRs to your peered namespaces | Read your Proxmox API token |
Observe metrics you forward for NR-* guests | Reach Proxmox without your operator |
| Peer over the Liqo/WireGuard path | Manage arbitrary non-NR- VMs |
Deeper product model: How it works.