Skip to main content

​
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

ConceptWhat it is
ClusterA registered k3s installation. Can be anywhere — homelab, edge, on-prem, cloud.
AgentThe Niro daemon running inside a cluster. Sends heartbeats, receives commands.
DeploymentA managed workload — a set of Kubernetes manifests you created via the builder or imported from Git.
EnvironmentA tag on a cluster: dev, staging, production, or unspecified. Affects policy severity.
RegistryStored credentials for pulling private container images.
IntegrationA connected external service, currently GitHub (for GitOps).
AlertA detected incident (cluster offline, pod crash-looping, etc.) with optional notifications.
Policy findingAn 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

Clusters

How clusters are registered, enrolled, and monitored.

Agents

How the in-cluster agent works, what it can do, and how to configure capabilities.

Deployments

How workloads are managed, applied, and rolled back.

Environments

How environment tagging affects policy severity and standards checks.
Last modified on June 12, 2026