Register an agent cluster

Run nr cluster register with the right flags, hypervisor credentials, and operator options

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.

Authenticate on the agent VM with a service account token (NR_API_TOKEN). Pass --org-id with the provider organization UUID from the console (or set NR_ORGANIZATION_ID). The CLI does not guess the organization from the API. --org-id only sets X-Organization-ID; it cannot replace a valid token. See Get started (VirtFusion) or Get started (SolusVM 2) for driver-specific credentials.

The CLI uses this organization's hypervisor driver (set when the provider organization is created). Pass --hypervisor-driver only if you need to confirm it; a mismatch is rejected.

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>

Flag	Required	Notes
`--name`	Yes*	Unique agent name in the organization
`--agent-id`	Yes*	Existing agent UUID from the UI install command; skips CreateAgent
`--agent-ip`	Yes (new register)	IPv4 NodeRings / Liqo should use to reach this VM
`--org-id`	Yes	Provider organization UUID (or `NR_ORGANIZATION_ID`)
`--gateway-region`	Yes (new register)	Currently `AMS01`

* 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

NodeRings never stores your Proxmox token. It stays in your cluster as a Kubernetes Secret consumed only by your operator.

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

Goal	Flag
Preview without changes	`--dry-run`
Non-interactive reuse / CI	`--yes`
Skip host prechecks (not recommended)	`--skip-prechecks`
Use local version pins (air-gapped experiment)	`--offline`
Extra namespaces to offload	`--offload-namespaces ns-a,ns-b`
Skip VNC offloading	`--disable-offloading`
JSON verify report on stdout at the end	`--output json`

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), or Get started (SolusVM 2).

Register an agent cluster

On this page