Register your first agent

This tutorial walks you through a complete first success: install the CLI on an agent VM, export a service-account token, register the cluster, and confirm it is healthy.

Plan about 20–40 minutes, depending on download speed and whether you install the hypervisor operator in the same run.

What you will end with

• nr on your PATH
• NR_API_TOKEN set from a service account (not OAuth on the VM)
• A peered agent cluster named something like edge-ams-01
• A passing nr cluster verify

Before you start

Confirm these are ready:

1. Provider organization verified (marketplace review approved).
2. A service account in that organization with a token that can create agents. Create it in the console under Access Control → Service Accounts.
3. A clean Ubuntu 22.04+ VM dedicated to the agent (2 vCPU, 4 GB RAM, outbound HTTPS).
4. The VM’s public IPv4 (or the address NodeRings and Liqo should use to reach the agent).
5. The organization UUID (--org-id). Create agent in the console copies a command that already includes it.
6. Gateway region AMS01 (currently the supported value).
7. Optional but recommended for a production agent: a hypervisor API token as described in Get started (Proxmox), Get started (VirtFusion), or Get started (SolusVM 2).

1. Install the CLI

On the agent VM:

curl -fsSL https://raw.githubusercontent.com/noderings/cli/main/scripts/install.sh | bash
nr version

If nr version prints a version string, continue.

2. Export the service account token

Do not run nr auth login or nr auth login --no-browser on the agent VM.

On the VM:

export NR_API_TOKEN='<service-account-token>'
echo $NR_API_TOKEN
nr auth status

echo $NR_API_TOKEN must print the JWT. You should see an authenticated status.

--org-id is not a credential. A missing token, an expired JWT, or a token from another organization is rejected.

3. Register the agent

Replace the placeholders with your values (or paste the command from Create agent):

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

What happens next (high level):

1. Create or reuse the agent record in NodeRings
2. Install k3s, then Calico, then Liqo
3. Peer with NodeRings and offload the VNC gateway namespace
4. Optionally install the hypervisor operator stack (unless you pass --skip-operator-install)
5. Run verify automatically at the end

The CLI may prompt for hypervisor credentials and related secrets when installing the operator. You can skip the operator on a first peering-only lab run:

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

If the run is interrupted, resume from the last checkpoint:

nr cluster register --resume --name edge-ams-01 --org-id <org-uuid>

4. Verify health

If register finished cleanly, verify already ran. Re-check anytime:

nr cluster verify --name edge-ams-01 --org-id <org-uuid>
nr cluster status --name edge-ams-01 --org-id <org-uuid>

A healthy result means Kubernetes, Calico, Liqo, and peering look good. Operator checks appear unless you skipped operator install.

5. Continue in the dashboard

Registration is only the connectivity half of onboarding. Next:

1. Confirm the agent shows as provisioned under Agents
2. Add platforms and nodes
3. Continue Get started (Proxmox), Get started (VirtFusion), or Get started (SolusVM 2) through plans and preflight

If something fails

For deeper background, read How registration works.