How It Works
What NodeRings is for hosting providers, onboarding, the agent model, and marketplace listing
NodeRings helps hosting providers sell on the NodeRings marketplace, where end users manage VMs from multiple providers in one API and GUI, or compare plans to find the best deal.
The platform was built to ease onboarding. You keep your infrastructure, billing, support, and day-to-day operations as they are today. NodeRings adds a control plane and optional marketplace channel without asking you to rip out existing systems.
No lock-in, no hypervisor access. You run a small agent on your own hardware and create a scoped Proxmox token locally. NodeRings sends orders through a peered channel. It never stores your hypervisor password or reaches your API directly. Ready to build? Jump to Get started.
Onboarding overview
To appear in marketplace search, work through these phases in order:
| Phase | Steps | Docs |
|---|---|---|
| Organisation | Register → verify organisation → verify domain | Organization type |
| Agent and region | Create region → install agent → add platform and nodes | Infrastructure sidebar |
| Cloud-init | Copy seed Ubuntu/Debian → customise for your OS | Cloud-init templates |
| VM templates | Create Proxmox qm template images → register VMID per node → link cloud-init | VM templates |
| IPAM | Create IPAM network on nodes (dual-stack prefixes) | Infrastructure sidebar |
| Plans and listing | Create plans and addons → preflight → live validation | Plans & Addons · Preflight Check |
When preflight and live validation pass for a plan on its nodes, the SKU appears in marketplace search.
For a step-by-step checklist with time estimates, continue to Get started.
The agent and operator model
Many providers are uncomfortable giving a marketplace direct API access to their hypervisor. NodeRings uses an operator pattern instead: a reconciliation loop you run in your environment, fully under your control.
Open source and least privilege
The agent stack (proxmox-operator, metrics sidecars, VNC gateway) is open source so you can review code quality and security before deployment.
NodeRings is designed for least privilege:
- NodeRings sends VM orders to a dedicated namespace on your agent cluster over the peering channel
- That namespace is scoped so NodeRings cannot read your Proxmox credentials or reach other workloads on the cluster
- Hypervisor secrets (Proxmox API tokens) live in your cluster and are read only by your operator
NodeRings is never able to read your hypervisor API token. It lives in your cluster and is consumed only by your own operator.
What a sale looks like
When a customer buys your plan on the marketplace, NodeRings does not call your Proxmox API directly. It sends a VM order to your agent cluster over the peering channel. Your proxmox-operator reconciles the order and talks to Proxmox on your LAN.
The diagram above shows the path: customer selects a plan → NodeRings sends the order to your agent → your operator provisions NR-{uuid} on Proxmox.
| Step | What happens |
|---|---|
| 1 | Customer purchases a plan (for example 8 vCPU / 16 GB at $48/mo) |
| 2 | NodeRings assigns IPs from your IPAM pools and builds the VM order |
| 3 | The order crosses the encrypted Liqo peering channel to your agent cluster |
| 4 | Your operator clones the template, applies cloud-init, and starts the VM as NR-{uuid} on Proxmox |
| 5 | Power actions, firewall updates, and scheduled backups follow the same pattern |
When your cloud-init templates reference organisation environment variables or secrets, NodeRings compiles those values in the backend at step 2 and passes final YAML to the operator: rotation of secrets does not affect VMs already running.
Customer VMs on Proxmox are always named NR-{uuid}.
Customer buys a plan
A customer purchases one of your plans on the marketplace.
NodeRings builds the VM order
NodeRings creates a VM record, assigns IPs from your pools, and sends CPU, RAM, disk, template, cloud-init, and static IP settings to your agent.
The order crosses the peering boundary
The order is delivered to your agent cluster over the encrypted peering channel.
Your operator provisions the VM
Your proxmox-operator watches for new orders, reads credentials from local secrets, and calls the Proxmox API to clone a template, apply cloud-init, and start the VM.
Power actions stay in sync
Power actions from the dashboard update the VM order; the operator reconciles stop/start on Proxmox.
Operator source: github.com/noderings/operator
What the operator handles
| Customer action | What your operator does |
|---|---|
| Create / delete VM | Clone template, apply cloud-init, assign VMID, start or remove guest |
| Start / stop / reboot | Update power state on Proxmox |
| Firewall rules | Push customer rulesets to the Proxmox VM firewall |
| Outbound SMTP | Apply provider DROP rules for TCP 25/465/587 when blocked (Network) |
| Backups | Run vzdump on schedule; restore on request |
| VNC console | Open Proxmox VNC proxy; relay session via your vnc-gateway |
NodeRings never embeds SSH keys, passwords, or Proxmox credentials in the order payload. Those stay in secrets on your agent cluster, read only by your operator. Full Custom Resource definitions are in the open-source operator repository.
Access beyond VM orders
Two capabilities also use the peering channel into your agent cluster. Both are scoped and auditable.
VNC console
End users open a VM console from the NodeRings UI. The flow keeps Proxmox off the public internet:
| Step | What happens |
|---|---|
| 1 | NodeRings requests a console session for the VM |
| 2 | Your operator opens a Proxmox VNC proxy and returns session details |
| 3 | The browser connects through vnc-gateway on your agent cluster |
| 4 | vnc-gateway dials the Proxmox VNC WebSocket inside your network and relays frames bidirectionally |
The gateway runs on your k3s cluster; only the proxied VNC session crosses the peering boundary.
Metrics
Metrics support dashboards, preflight checks, and capacity / overallocation decisions.
Grafana Alloy on your agent scrapes local Proxmox metrics every 30s, keeps cluster/node/storage series in full, keeps per-VM series only for guests named NR-{uuid}, and forwards them to NodeRings.
See Agents → Metrics forwarded to NodeRings for the full table.
Nodes
Node-level series (pve_up, CPU, memory, storage) feed platform online and plan capacity preflight, plus overallocation and placement logic.
Billing and payouts
Marketplace sales are processed through Stripe. Connect your payout account at /billing/payout using Stripe Connect.
| Setup | What happens |
|---|---|
| Stripe Connect | Customer payments land in your Stripe account directly and immediately after each sale |
| Manual payout | NodeRings holds funds and pays you out manually after dispute risk is low, typically 60 to 120 days |
Stripe Connect keeps revenue with you instead of passing through NodeRings settlement. With manual payout, NodeRings holds customer payments until the chargeback window is largely past, then releases them to you.
Your provider subscription and platform fees are separate from customer VM revenue. See Billing for dashboard paths and setup.
Next
Continue with Get started for the full setup checklist.