> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niro.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a Cluster

> Enroll a k3s cluster with Niro in under 60 seconds.

## Prerequisites

* A running [k3s](https://k3s.io) cluster
* `kubectl` configured to talk to it
* A Niro account — [sign up free](https://app.niro.cx/signup)

## 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](/concepts/environments) 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:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -fsSL https://get.niro.cx/install.sh | NIRO_TOKEN=<your-token> sh
```

<Warning>
  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.
</Warning>

### What the installer does

1. Creates the `niro-system` namespace
2. Sets up read-only cluster permissions for the agent
3. Deploys the Niro agent 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

<Check>
  The cluster is connected when the last heartbeat timestamp shows a time within the last 30 seconds.
</Check>

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):

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
# 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](/reference/agent-capabilities) for the full list.

## Troubleshooting

### The cluster doesn't appear after running the installer

Check that the agent pod is running:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
kubectl get pods -n niro-system
```

If the pod is in `CrashLoopBackOff` or `Error`, check the logs:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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.

## Related

* [Agent Capabilities](/reference/agent-capabilities) — opt-in RBAC grants
* [Clusters](/concepts/clusters) — cluster lifecycle and status
* [Deploy an App](/guides/deploy-app) — deploy your first workload after connecting