Get Started (VirtFusion)

Create a group

Hypervisor groups → Create Group. Name it for the site (for example edge-1). Copy the ID column — that is the NodeRings group id. Leave the built-in Default group empty.

Add and commission the hypervisor

Hypervisors → Add Hypervisor. Set name and the host’s management IP (the address that serves :8892, not a guest IP). On an all-in-one install, that is the control server itself.

Open the hypervisor → Test Connection → commission. Wait until it is commissioned and enabled. Copy the hypervisor id in the table — it is not the group id.

Limits, storage, and network

On General, set max servers, memory (leave a few GiB for the host), and virtual CPU. Assign the group from the previous step.

On Storage, enable a local mountpoint (often /home) and set Maximum Disk.

On Network, set Type to MacVTap and Interface name to the NIC guests should use (eth0 or ens18). Use a Linux bridge (br0) if you need filtering.

Create the block

Create IP Block → name it → type IPv4. On General, set gateway, netmask, and resolvers → Enabled → Save Settings.

Add the range

Add start–end addresses. Do not include the hypervisor or gateway unless you intend to assign them to guests. On Addresses, every IP should show Available.

Assign the hypervisor

Select the hypervisor → Assign Hypervisor. Bind it to Primary (eth0 or your bridge) and Update.

Install images

From Updates / Available, install the distros you will sell (Ubuntu 22.04/24.04, Debian 12/13, and so on). Prefer Cloud Micro or other cloud-init images. Wait until each row is Enabled and Cloud-Init: YES.

Copy each OS id

Open each template and copy the numeric id from the URL. That is the NodeRings VM template template ID.

Create a shared package

Name it (for example nr-shared-2c-4g). Set CPU, memory, and disk for the shared VPS you will sell → Enabled. NodeRings VirtFusion nodes are shared only.

Template collection

Leave Allow All, or attach a collection that includes the templates above.

Copy the package id

The ID column on Server Packages is what you enter on the plan later.

Open Global API

In the VirtFusion admin sidebar, Settings → Global API (breadcrumb Dashboard → Global API). Click Create Token.

Name the token

Name (for example noderings-agent). Leave Access empty until you know the agent’s egress IPs (blank = any connection). Confirm your admin password if asked. Click Create.

Copy the secret once

The green box shows vf_live_… once. Copy it to a password manager. It cannot be read again from the list (the table only shows name, permissions, and status).

Create the client user

In the VirtFusion admin sidebar, open Users → Create. Use a dedicated name (for example noderings). Give the account a real email you control. This must be a client user, not an admin. After create, copy the numeric user id from the Users table (or from the user URL). You will paste that id on the agent as VIRTFUSION_USER_ID.

Log in as that user

Sign out of the admin panel. Open the client area and log in as the user you just created. Complete any first-login password change if the panel asks.

Generate a User API token

While logged in as that client user, open Account → API (sometimes labelled API tokens). Create a token. Copy the secret once into a password manager. That value is VIRTFUSION_USER_API_TOKEN. It is not the Global API token from Settings → Global API.

Create a provider organization

In the sidebar, open the organization menu → Add organization → choose Provider (sells services to clients) → enter your company name → Create Organization.

Verify your domain

On Provider onboarding, enter the domain you will list on the marketplace (for example acme.com) and choose a verification method:

Click Add Domain, apply the challenge, then Verify. DNS can take a few minutes to propagate.

Complete your organization profile

Fill in the details NodeRings uses for marketplace review and customer-facing listings:

• Organization name (legal company name)
• Support email, billing email, and support phone
• Business address (country, region, city, postcode)
• Tax identifiers (VAT ID, tax ID where applicable)
• DDoS provider and ASN (if you operate your own network)
• Provider logo (PNG or SVG, max 512 KB)
• Business owner name and social profiles (optional)

Request review

Click Request review and save. NodeRings reviews your listing; infrastructure unlocks after approval. Set up Stripe Connect under Organization → Billing → Payout when ready.

Choose how to connect

On Payout Methods → Connect Account, choose Create Connect Account or Use existing Stripe account. Creating a new account still opens Stripe's hosted onboarding (signing in there can reuse verified business and bank details, but NodeRings still gets a new Stripe account). Use existing connects the Stripe account you already use, including its balance and payout history. The existing account must be a Standard account that is not connected to another platform or to a different NodeRings organization. Disconnect a manual payout account first if one is configured.

Complete Stripe onboarding

If you created a new account, status is Pending and charges and payouts stay disabled until you finish Stripe's hosted form. Click Complete Setup & Onboarding, provide business and identity details, then return to the dashboard.

Confirm Active

When onboarding succeeds, the account shows Active with Charges Enabled and Payouts Enabled. You can set a payout schedule under Payout Schedule. If Stripe Connect is not available in your country, use Manual Payout instead (funds are held longer before release).

Pick the geography

Select country and city that reflect where your VirtFusion hypervisors actually run. This is what customers use to choose your plans.

Choose datacenter

Select the facility from the list, or choose Other if you do not want to disclose your datacenter provider on the marketplace. Other still lets you sell, only the specific facility name is hidden.

Choose availability zone

Pick zone_a, zone_b, or another zone only when the infrastructure is truly separate (distinct top-of-rack switches, routers, or hypervisor rows). If everything shares one fabric, use a single zone. Splitting zones without real isolation misleads customers about fault tolerance.

Save the region

Click Create Region. The region is then available when you attach nodes and plans.

Register the agent

Enter an agent name and the VM’s public IPv4 address. These are the only required fields to establish the secure channel between your site and NodeRings. Description is optional.

Choose gateway region

Select the gateway region closest to your agent VM. This is the datacenter where the NodeRings control-plane cluster runs. Picking a nearby gateway keeps the peering tunnel short and stable (for example Amsterdam if your agent sits in western Europe).

Provision on your agent VM

After you create the agent it appears as Unprovisioned. Select it in the list, open the Provisioning tab, and copy the Installation command. SSH into your Ubuntu agent VM and paste the command there.

You must pass VirtFusion as the driver (the default installs Proxmox). Prefer Create agent in the console: it copies a command that already includes --org-id.

On the agent VM, use a service account token (Access Control → Service Accounts). Do not run nr auth login on the VM:

export NR_API_TOKEN='<service-account-token>'
echo $NR_API_TOKEN
nr cluster register \
  --name "Frankfurt VirtFusion" \
  --agent-ip <public-ipv4> \
  --gateway-region AMS01 \
  --hypervisor-driver virtfusion \
  --org-id <org-uuid>

When prompted, provide the control origin, Global API token, client username, numeric user id, and User API token:

export VIRTFUSION_URL="https://cp.example.com"
export VIRTFUSION_TOKEN="…"              # Global API; agent Secret only
export VIRTFUSION_USER_NAME="noderings"
export VIRTFUSION_USER_ID="5"
export VIRTFUSION_USER_API_TOKEN="…"     # User API; agent Secret only
nr cluster register --hypervisor-driver virtfusion --name edge-vf-01 --agent-ip 203.0.113.10 --gateway-region AMS01 --org-id <org-uuid>

The CLI installs k3s, Calico, Liqo peering, and virtfusion-operator into virtfusion-system (not proxmox-system).

Verify

On the agent:

nr cluster verify --name edge-vf-01

Expect Helm namespace virtfusion-system, CRDs in vm.virtfusion.com, and Deployments for the VirtFusion operator, exporter, Alloy, and vnc-gateway.

Add a platform

Give it a name, select driver VirtFusion, and choose the agent you provisioned. API tokens are not entered here — they stay on the agent.

Set the endpoint URL

Enter the control-server origin only, for example https://cp.example.com. Do not append /api/v1. Do not use a hypervisor management IP.

The agent VM must be able to reach this URL. The operator probes GET /connect. The platform is online when that succeeds and hypervisor metrics flow (vf_hypervisor_up). The endpoint URL cannot be changed after the platform is created.

Add a node

Under your platform, click Add Node. Enter:

Attach region

Select the region from §3 Region where this host physically sits.

Skip Proxmox-only fields

Do not fill vmbr0, local-lvm, VMID seed, vzdump, NIC model, or dedicated/topology. VirtFusion nodes are shared only.

Resource overallocation

Set CPU, memory, and storage overallocation percentages for this node:

A plan still cannot exceed a single node’s physical size.

Register in NodeRings

Click Create VM Template. Select node, distro, and the VirtFusion operating-system id (the number in the template URL).

Cover the catalog you sell

Preflight expects every OS you list to be registered on the node. Match the distro to the VirtFusion image (Ubuntu 24.04 Cloud Micro → Ubuntu 24.04, and so on).

Create a plan

Plans tab → Create Plan → shared billing type, region, and template. Set VirtFusion package id to the package from Server package (metadata.virtfusion.package_id).

CPU throttle and network rate

CPU throttle is a percent (NodeRings 0–100 maps to VirtFusion 0–99). Ignore cpuUnits. Enter NIC rate in MB/s as usual; the operator converts to kB/s.

Create addons

Required marketplace addon for VirtFusion: ADDITIONAL-IP only. Do not require DAILY-BACKUP or WEEKLY-BACKUP. NodeRings does not create on-demand backups on VirtFusion.

Wait for preflight to go green

Fix red gates (agent, platform, node, templates, addons). The next automatic cycle usually picks up changes within a few minutes.

Run live validation per plan × node

Use Start validation for every combination you sell on. Repeat when you add nodes or plans.

Confirm marketplace ready

Summary shows Ready with no blockers, and live validation shows Validated: Yes for at least one node in the sell region.

Customers can find and buy your plan

On the client marketplace, your organization name, plan price, and listing details appear under recommendations.