> ## 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.

# Core Concepts

> Understand the building blocks of Niro — clusters, agents, deployments, and more.

## The big picture

Niro is organized around a simple model:

```
Organization
 └── Clusters (one per k3s installation)
      ├── Agent (runs inside the cluster)
      ├── Deployments (workloads you manage)
      └── Pods (all running workloads, managed or not)
```

An **organization** is the top-level container for your fleet. Members of an organization can see and manage all clusters in that org. For MSP use cases, organizations form a tree — a parent org's members can see all child orgs' clusters.

## Concepts at a glance

| Concept            | What it is                                                                                           |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Cluster**        | A registered k3s installation. Can be anywhere — homelab, edge, on-prem, cloud.                      |
| **Agent**          | The Niro daemon running inside a cluster. Sends heartbeats, receives commands.                       |
| **Deployment**     | A managed workload — a set of Kubernetes manifests you created via the builder or imported from Git. |
| **Environment**    | A tag on a cluster: `dev`, `staging`, `production`, or `unspecified`. Affects policy severity.       |
| **Registry**       | Stored credentials for pulling private container images.                                             |
| **Integration**    | A connected external service, currently GitHub (for GitOps).                                         |
| **Alert**          | A detected incident (cluster offline, pod crash-looping, etc.) with optional notifications.          |
| **Policy finding** | An advisory standards check surfaced at build time, PR time, or runtime.                             |

## Data flow

Understanding how data moves through Niro helps reason about latency and consistency:

### Heartbeat (cluster → Niro)

Every \~15 seconds the agent posts a heartbeat containing:

* Node inventory (name, status, roles, Kubernetes version, CPU/memory capacity and usage)
* Pod inventory (phase, restarts, owner, resource requests/limits/usage, images, probe config)
* Kubernetes Warning events (recent window)
* Capabilities the agent has been granted (logs, apply, self-update)

Niro processes the incoming data, updates the cluster snapshot, runs policy checks, and evaluates incident conditions.

### Commands (Niro → cluster)

Commands travel in the opposite direction via a persistent connection the agent maintains to Niro. When a command is ready, Niro delivers it over that connection. This means all traffic is **outbound from the cluster** — no inbound ports are needed.

Commands include applying or removing manifests, streaming pod logs, and liveness checks.

### Dashboard polling

The dashboard refreshes every 5 seconds for live fleet state. The fleet overview page loads a static shell instantly and streams the live cluster data on first load, after which the client takes over for live updates.

## Next steps

<CardGroup cols={2}>
  <Card title="Clusters" icon="server" href="/concepts/clusters">
    How clusters are registered, enrolled, and monitored.
  </Card>

  <Card title="Agents" icon="microchip" href="/concepts/agents">
    How the in-cluster agent works, what it can do, and how to configure capabilities.
  </Card>

  <Card title="Deployments" icon="rocket" href="/concepts/deployments">
    How workloads are managed, applied, and rolled back.
  </Card>

  <Card title="Environments" icon="layer-group" href="/concepts/environments">
    How environment tagging affects policy severity and standards checks.
  </Card>
</CardGroup>