Register an agent cluster

nr cluster register creates (or reuses) an agent in your organization, installs the local stack on the VM, peers with NodeRings, and optionally installs the hypervisor operator.

Pass --hypervisor-driver proxmox, virtfusion, or solusvm to sell virtual machines. Pass --pterodactyl to sell game servers. The CLI asks for the panel URL, keys, and user id unless those are already set with flags or PTERODACTYL_* variables. Pass both flags to install both. Omit --hypervisor-driver only when --pterodactyl is set. An organization keeps one hypervisor; a different value is rejected. See Install an agent for Pterodactyl.

For the conceptual phase order, see How registration works. For every flag, see cluster register reference.

Minimal production-shaped command

nr cluster register \
  --name edge-ams-01 \
  --agent-ip 203.0.113.10 \
  --gateway-region AMS01 \
  --org-id <org-uuid>

* Provide --name and/or --agent-id. With only --agent-id, the name is resolved from the API.

Reuse an existing agent

Same name already exists:

nr cluster register --name edge-ams-01 --agent-ip 203.0.113.10 --gateway-region AMS01 --org-id <org-uuid> --yes

--yes reuses without an interactive prompt. --force implies cleanup and non-interactive reuse for destructive re-runs — use carefully on live agents.

From the dashboard install command (agent already created):

nr cluster register \
  --agent-id <agent-uuid> \
  --agent-ip 203.0.113.10 \
  --gateway-region AMS01 \
  --org-id <org-uuid> \
  --yes

Reinstalling over a provisioned agent via --agent-id also requires --force or --yes.

Operator install (Proxmox)

By default, register installs the proxmox-operator Helm chart after peering. Supply credentials one of three ways:

1. Interactive prompts

Run without --yes. The CLI prompts for Proxmox URL, username, token ID, and token secret (HTTPS URLs only).

2. Environment variables (single instance)

export PROXMOX_URL="https://pve.example.com:8006"
export PROXMOX_USERNAME="nrings-operator@pve"
export PROXMOX_TOKEN_ID="nrings-operator-token"
export PROXMOX_TOKEN_SECRET="..."
# optional:
export PROXMOX_INSTANCE_ID="pve-ams-1"

3. Instances file (one or many)

# chmod 600 required — group/world-readable files are rejected
instances:
  - id: pve-ams-1
    url: https://pve.example.com:8006
    username: nrings-operator@pve
    tokenId: nrings-operator-token
    tokenSecret: "..."

nr cluster register \
  --name edge-ams-01 \
  --agent-ip 203.0.113.10 \
  --gateway-region AMS01 \
  --org-id <org-uuid> \
  --proxmox-instances-file /secure/proxmox-instances.yaml \
  --yes

Game servers (Pterodactyl)

Pass --pterodactyl on nr cluster register, or run nr cluster install-pterodactyl when the agent is already registered. It does not set a hypervisor. The CLI asks for the panel URL, application key, client key, and panel user id. The keys stay visible as you type.

Skip a question by exporting the value before you run the command. --yes does not prompt, so a script must set all four. Put the key itself in the variable:

export PTERODACTYL_PANEL_URL="https://panel.example.com"
export PTERODACTYL_APPLICATION_KEY="ptla_..."
export PTERODACTYL_CLIENT_KEY="ptlc_..."
export PTERODACTYL_PANEL_USER_ID="3"

Full steps: Install an agent for Pterodactyl.

Wrong URL, token, or panel key

A typo is stored only on the agent. Resume and answer again if the Secret was never written. If the operator is already installed, pass the corrected PROXMOX_*, VIRTFUSION_*, or SOLUSVM_* values with --resume --reinstall-operator. Without those values, reinstall keeps the old Secret. For a Pterodactyl panel, unset PTERODACTYL_* and run nr cluster install-pterodactyl again, then restart the operator. Commands: Resume, recover, and roll back.

Operator install configures Alloy remote_write with a Bearer metrics write token. Leave MIMIR_BEARER_TOKEN unset so the CLI issues (or rotates) a credential via the platform API and stores it in your cluster Secret. You may set MIMIR_BEARER_TOKEN explicitly to reuse a token you already manage. Interactive mode can prompt for an optional override; CI normally leaves it unset.

Skip the operator (lab / peering only)

nr cluster register \
  --name lab-01 \
  --agent-ip 203.0.113.10 \
  --gateway-region AMS01 \
  --org-id <org-uuid> \
  --skip-operator-install

Install or re-run the operator later with --resume --reinstall-operator (do not combine with --skip-operator-install).

Useful options

After register

nr cluster verify --name edge-ams-01
nr cluster status --name edge-ams-01

Then continue platform/node setup in Get started (Proxmox), Get started (VirtFusion), Get started (SolusVM 2), or Get started (Pterodactyl).