Nebua Agent Installation Guide

The Nebua Agent is the host-level communication service for private clusters. It runs directly on the target Linux host with systemd, connects outbound to NebuaCloud, and owns local k3s lifecycle tasks such as bootstrap, health checks, restart, and kubeconfig sync. Autonomous add-on reconciliation, policy enforcement, and self-healing belong to nebua-operator inside the cluster instead — see the Operator Installation Guide to install it. For exposing an environment's reverse proxy, see the Gateway Installation Guide. Nebua Runtime Components explains how the three fit together.

Install nebua-agent.service on the first control-plane node at minimum. For stronger node-level visibility, install it on every private cluster node and set NODE_TYPE appropriately.

Every node needs its own agent ID and its own token — never reuse one pair across multiple hosts. Generate a separate token from the dashboard's API Keys tab for each node you install on (control-plane or worker). The generated token has that node's agent ID baked into it, so --agent-id and --token on a given host must be the matching pair from the same generation — not values copied from another node's install command. Reusing one pair across two hosts makes Core treat them as a single agent reconnecting back and forth: whichever host's connection is currently registered silently overwrites the other's, so commands like listing nodes intermittently reach a host that may not even have cluster API access (a plain k3s worker has no /etc/rancher/k3s/k3s.yaml), and the dashboard ends up missing nodes unpredictably.

Prerequisites

• Ubuntu, Debian, or another systemd-based Linux host
• curl and tar
• Outbound HTTPS/WebSocket access to NebuaCloud on port 443
• Cluster ID, agent ID, and NebuaCloud agent token from the dashboard
• Root access on the target host
• cgroup v2 enabled if the cluster runs k3s v1.32 or newer (see Host Requirement: cgroup v2)

The hosted installer downloads a Nebua agent bundle that already contains the Node.js runtime and compiled agent code. The target host does not need Node.js, pnpm, or a monorepo checkout.

The agent should run as root for production private-cluster hosts because it manages local k3s bootstrap and service operations through systemd.

Host Requirement: cgroup v2

Kubernetes removed cgroup v1 support, so k3s v1.32 and newer require the host to run the unified cgroup v2 hierarchy. On a cgroup v1 host the kubelet refuses to start, k3s never becomes ready, and the node never registers — so the cluster shows "not connected" and any worker join silently fails to appear. Older distributions (e.g. Ubuntu 20.04 / kernel 5.4) default to cgroup v1.

The agent cannot change the cgroup hierarchy for you: switching to cgroup v2 requires a kernel boot parameter and a host reboot, which the agent will not perform automatically. The agent detects the mismatch and reports an actionable error; the host owner must apply the change.

Check the host's cgroup version:

# Prints "CGROUP_V2" when the host is ready for k3s v1.32+, otherwise "CGROUP_V1"
test -f /sys/fs/cgroup/cgroup.controllers && echo CGROUP_V2 || echo CGROUP_V1

Enable cgroup v2 (Ubuntu/Debian with GRUB):

# 1. Add the kernel flag (idempotent)
sudo sed -i 's/^GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"/GRUB_CMDLINE_LINUX_DEFAULT="\1 systemd.unified_cgroup_hierarchy=1"/' /etc/default/grub

# 2. Regenerate the boot config and reboot
sudo update-grub
sudo reboot

# 3. After reboot, confirm cgroup v2 is active
test -f /sys/fs/cgroup/cgroup.controllers && echo CGROUP_V2 || echo CGROUP_V1

Alternatives if you cannot reboot to cgroup v2:

• Pin the cluster to a cgroup-v1-compatible k3s release (v1.31 or older, e.g. v1.29.3+k3s1). All nodes must use the same line — a cgroup-v1 worker cannot join a k3s v1.32+ control plane.
• Set NEBUA_K3S_CGROUPV1_VERSION in /etc/nebua/nebua-agent.env to force a compatible version on cgroup-v1 hosts.

A node that was added before fixing cgroup may leave stale state under /var/lib/rancher/k3s. After enabling cgroup v2, remove it (sudo rm -rf /var/lib/rancher/k3s /usr/local/bin/k3s /usr/local/bin/kubectl) so the next join installs cleanly.

Quick Host Installation

Run the hosted installer on the target host. The NebuaCloud dashboard should generate this command with the correct cluster ID, agent ID, and token — the agent ID is auto-generated when you create the token and shown alongside it in the dashboard's API Keys tab; it must be passed through so it matches the ID embedded in the token, otherwise the agent generates its own random ID locally and /v1/agent/validate rejects it as a mismatch.

curl -fsSL https://nebuacloud.com/install/nebua-agent.sh | sudo bash -s -- \
  --cluster-id <cluster-id> \
  --agent-id <control-plane-agent-id> \
  --token '<control-plane-agent-token>' \
  --node-type control-plane \
  --env production

For worker nodes, generate a separate token from the dashboard for each worker host — do not reuse the control-plane's --agent-id/--token pair here, or any other worker's:

curl -fsSL https://nebuacloud.com/install/nebua-agent.sh | sudo bash -s -- \
  --cluster-id <cluster-id> \
  --agent-id <worker-agent-id> \
  --token '<worker-agent-token>' \
  --node-type worker \
  --env production

The hosted bootstrap script downloads the NebuaCloud agent bundle for the selected release, runs the host installer, installs bundled Node under /usr/local/lib/nebua/bin/node, installs the runtime under /usr/local/lib/nebua/runtime, writes /etc/nebua/nebua-agent.env, installs /etc/systemd/system/nebua-agent.service, and starts the service.

Environment File

The systemd unit reads configuration from /etc/nebua/nebua-agent.env. This file is owned by root and installed with 0600 permissions.

BUILD_ENV=production
NODE_ENV=production
NEBUACLOUD_API_URL=https://api.nebuacloud.com
CLUSTER_ID=605819
NEBUACLOUD_TOKEN=token
AGENT_ID=nebua-agent-xxx
NODE_TYPE=control-plane

Common values:

• CLUSTER_ID: NebuaCloud cluster ID
• NEBUACLOUD_TOKEN: agent token with agent connection scopes
• NEBUACLOUD_API_URL: API base URL, defaults to https://api.nebuacloud.com
• AGENT_ID: stable host agent ID - must match the agent ID the token was generated with, or /v1/agent/validate rejects the token as not valid for this agent
• NODE_TYPE: control-plane, server, worker, or agent

After changing the env file, restart the service:

sudo systemctl restart nebua-agent

Verify Installation

sudo systemctl status nebua-agent --no-pager
sudo journalctl -u nebua-agent -f

Check k3s after bootstrap:

sudo systemctl status k3s --no-pager
kubectl get nodes

The agent writes the kubeconfig in readable mode (write-kubeconfig-mode: 0644), so kubectl works directly — no sudo or k3s prefix needed.

The agent should validate its token, connect to NebuaCloud, bootstrap or detect k3s, then report cluster health.

Updating The Agent

To update the agent, rerun the hosted installer with the same cluster values:

curl -fsSL https://nebuacloud.com/install/nebua-agent.sh | sudo bash -s -- \
  --cluster-id <cluster-id> \
  --agent-id <agent-id> \
  --token '<agent-token>' \
  --node-type control-plane \
  --env production

The installer replaces /usr/local/lib/nebua/runtime, refreshes the env file, reloads systemd, and restarts nebua-agent.service.

Troubleshooting

Agent does not start

sudo journalctl -u nebua-agent -n 100 --no-pager

Common causes:

• missing or invalid NEBUACLOUD_TOKEN
• missing CLUSTER_ID for an existing cluster
• target host cannot reach NEBUACLOUD_API_URL
• curl or tar is missing during initial installation

k3s does not become healthy

sudo systemctl status k3s --no-pager
sudo journalctl -u k3s -n 100 --no-pager
sudo journalctl -u nebua-agent -n 100 --no-pager

The agent reports host recovery signals, but autonomous remediation belongs to nebua-operator. Disk pressure, unsupported kernels, broken cgroups, or occupied ports may still require manual host cleanup.

Security Considerations

• The agent connects outbound only; no inbound firewall rule is required.
• Store tokens only in /etc/nebua/nebua-agent.env or your secret manager.
• Keep /etc/nebua/nebua-agent.env owned by root with 0600 permissions.
• Rotate tokens after accidental exposure in shell history, logs, tickets, or screenshots.