Skip to main content

​
Prerequisites

  • A running k3s cluster
  • kubectl configured to talk to it
  • A Niro account — sign up free

​
1. Create the cluster in Niro

In the Niro dashboard, click Add cluster (on the Fleet page or the empty state if this is your first cluster). Fill in:
  • Name — a descriptive label for this cluster (e.g. homelab, edge-berlin, customer-acme)
  • Environment — dev, staging, production, or leave as unspecified. This affects policy severity and can be changed later.
Click Create. Niro generates a single-use enrollment token valid for 1 hour.

​
2. Run the install command

Copy the install command shown in the dialog and run it on any machine with kubectl access to the cluster: 
curl -fsSL https://get.niro.cx/install.sh | NIRO_TOKEN=<your-token> sh
The enrollment token is single-use and expires in 1 hour. If you need a new token, delete the cluster and add it again, or click Regenerate token in the cluster settings.

​
What the installer does

  1. Creates the niro-system namespace
  2. Creates a ClusterRole and ClusterRoleBinding (read-only by default)
  3. Deploys the Niro agent as a Deployment in niro-system
  4. The agent enrolls with Niro, exchanges the token for a long-lived key, and stores it in a Secret
The entire install takes about 15–30 seconds depending on image pull time.

​
3. Verify the connection

Return to the Niro dashboard. Within ~15 seconds you’ll see:
  • The cluster appear in the Fleet list with a Healthy status badge
  • A node count (e.g. 1 node)
  • A ticking last heartbeat timestamp
The cluster is connected when the last heartbeat timestamp shows a time within the last 30 seconds.
Click the cluster name to open the detail view and see live node metrics and pod inventory.

​
Enabling capabilities

The default agent installation is read-only. To unlock additional features, re-run the installer with capability flags (no new token needed — the agent reuses its existing enrollment): 
# Enable live log streaming
curl -fsSL https://get.niro.cx/install.sh | NIRO_ENABLE_LOGS=1 sh

# Enable manifest apply (GitOps and visual builder)
curl -fsSL https://get.niro.cx/install.sh | NIRO_ENABLE_APPLY=1 sh

# Enable both at once
curl -fsSL https://get.niro.cx/install.sh | NIRO_ENABLE_LOGS=1 NIRO_ENABLE_APPLY=1 sh
The capability appears in the dashboard within ~15 seconds. See Agent Capabilities for the full list.

​
Troubleshooting

​
The cluster doesn’t appear after running the installer

Check that the agent pod is running: 
kubectl get pods -n niro-system
If the pod is in CrashLoopBackOff or Error, check the logs: 
kubectl logs -n niro-system -l app=niro-agent
Common causes:
  • Invalid token — the token expired or was already used. Regenerate it and try again.
  • Network connectivity — the cluster can’t reach api.niro.cx. Check that outbound HTTPS (port 443) is allowed.
  • Wrong kubeconfig — kubectl is pointing at a different cluster than you think.

​
The heartbeat shows “Unknown” or “Offline”

If the cluster enrolled but the heartbeat stopped:
  • Check the agent pod is still running: kubectl get pods -n niro-system
  • Check outbound connectivity from the cluster to api.niro.cx
  • Check the agent logs for authentication errors (the key may have been rotated)

​
I need to reinstall without losing the cluster

Re-running the installer on an already-enrolled cluster is safe — it preserves the existing enrollment and key, and only updates the RBAC and Deployment if the flags change.

​
Uninstalling

To fully remove the agent from a cluster: 
kubectl delete namespace niro-system
This removes the niro-system namespace and all resources inside it (the agent Deployment, RBAC, and the key Secret). Then delete the cluster from the Niro dashboard.
Last modified on June 12, 2026