// Betrieb
Onboarding a new location
Onboarding gives a location's spoke-agent the credentials it needs to publish metrics to the hub. The agent authenticates once with a registration token, exchanges it for scoped NATS credentials, and then runs on its own. The token is time-limited and works for one agent: after its first use it only lets that agent retry for 5 minutes, so it's safe to hand to an installer.
Prerequisite: the location exists in inventory — see creating a location — and (usually) has at least one resource to collect — see adding a resource.
Connecting a Proxmox homelab? For the full sequence — monitoring-token creation, the exact credential format, self-signed TLS, and the registry to use — follow the end-to-end Connect a Proxmox homelab walkthrough, which threads this page together with the resource and credential steps.
The normal flow (registration token)
- Open Locations.
- On the location's row, select Onboard. Fleeger mints a one-time
registration token (requires the
location.createpermission) and shows a ready-to-run install command. Pick your platform — Docker, Kubernetes, or Standalone — and the command updates to match (see Run the agent as a container for what each one does). The hub's ownmetalocation has no agent and offers no Onboard: the hub monitors itself, and a token for it is refused. - Run that command where the agent will live (a Pi in the homelab, a pod in the
cluster, …). On first boot the agent:
- calls
POST /api/bootstrapwith the token (the token is its only credential), - receives NATS user credentials scoped to this location,
- writes them plus a
<creds>.meta.json, and discards the token.
- calls
- The agent connects to NATS and starts publishing. Within ~30s the location flips to reachable on the dashboard (see checking reachability).
On later restarts the agent reuses the persisted credentials — it never needs the token again. That also means a new token is ignored while they are there: to onboard the location again (after offboarding, or to start over), remove them first (see re-onboarding).
Run the agent as a container
The spoke-agent is published as a container image and configured entirely by
environment variables (or a small TOML file). It connects to the hub over a
single URL: it bootstraps over HTTPS, then does everything else — metrics
and inventory (reading targets, revealing credentials, reporting discovery /
hardware) — over the encrypted NATS WebSocket the hub hands it (wss://<hub>/nats).
So a remote agent needs only the one public endpoint; nothing else must be
exposed. See agent security
for the trust model.
If that endpoint is behind an ingress, a load balancer or a tunnel, the edge
has to trust it, or it answers both the bootstrap and /nats with a 503. A
new agent then exits with a "bootstrap rejected" error naming the 503; one
that already bootstrapped fails when it connects to /nats. The response
itself says why ("Fleeger is behind a proxy the edge does not trust…"); fetch
the hub URL with curl -i to read it. The same setting decides whether
offboarding can revoke the
agent later.
If nothing answers at all (a firewall dropping the traffic, a proxy that holds the request), the first boot gives up instead of waiting forever: the agent exits with "bootstrap … timed out", after 10s if it could not connect and after 30s if it connected but got no answer.
An agent whose first boot fails (a timeout, a refused token, an unreachable
NATS) exits and is started again: the pod on Kubernetes, the container on
Docker through --restart unless-stopped in the commands below. A docker run
without --restart stays stopped until you start it again. An exchange the
hub could not record leaves the token unused, and the retry is a first
exchange. Once the hub has recorded the agent's credentials, the token is used
up, even if the answer never reaches the agent. For 5 minutes after that the
same token still works: a retry gets fresh credentials, and the ones from the
lost answer are revoked (up to 4 retries). A retry the hub refuses within
those 5 minutes can simply be tried again. If one is refused as an
already-used token after that, mint a new one with Onboard. Whoever sees a
used token within those 5 minutes could also exchange it, and the agent then
loses its credentials; treat the token as secret until the agent is up. On
Docker, remove the old container first (docker rm -f fleeger-agent), or the
new docker run fails because the name is taken.
| What | Config | Notes |
|---|---|---|
| Hub URL | FLEEGER_HUB_URL |
The one endpoint — same origin as the UI. https://, with no credentials, query or fragment; the agent refuses anything else before it sends the token. http:// works but sends the token and the agent's credential in cleartext, so the agent warns unless the host is loopback or a single-label name such as edge. |
| Token | FLEEGER_REGISTRATION_TOKEN |
The one-time token from Onboard. |
| Creds path | FLEEGER_NATS_CREDS |
Where bootstrap writes creds (default /var/lib/fleeger/agent.creds). Must persist — the token stops working 5 minutes after its first use. |
| Poll interval | FLEEGER_POLL_INTERVAL_SECS |
Seconds between collection cycles (default 30; 0 is ignored). Keep it well under 90s: each resource reports once per cycle, and its alerts treat 90s of silence as unreachable (the location's heartbeat is sent at least every 30s regardless). |
| State dir | FLEEGER_STATE_DIR |
Where the agent keeps the clusters it last read for its Proxmox and Kubernetes registrations, so a restart keeps their series' identity (default: the creds file's directory). Should persist, like the creds. |
Image and registry. The Docker Onboard command runs
registry.netcode.dev/fleeger/spoke-agentat your hub build's version, and the Kubernetes one pulls the chart and image fromregistry.netcode.dev/fleegerat that version too. A hub build without a release version (a local build) puts<version>there; fill in the version yourself. If you mirror or push the images to your own registry (see container images), substitute it in either command.
Keeping the token off the command line. Neither the commands below nor the ones the Onboard panel copies pass the token as an argument to
docker,kubectlorhelm, where any local user could read it withpswhile the command runs. It is handed over in a private file (Docker) or a Secret (Kubernetes), written byprintf, a shell builtin. The panel's commands carry the token inline, so it lands in your shell history (a file only you can read); the ones below ask for it at a prompt that does not echo it and keep it out of the history too. All of them are for sh, bash or zsh, not fish. The Secret is applied, so running the Kubernetes commands again with a new token replaces the old one.
Docker
printf 'Registration token: '; stty -echo; IFS= read -r FLEEGER_TOKEN; stty echo; echo
(umask 077; rm -f fleeger-agent.env; printf 'FLEEGER_REGISTRATION_TOKEN=%s\n' "$FLEEGER_TOKEN" > fleeger-agent.env)
unset FLEEGER_TOKEN
docker run -d --restart unless-stopped --name fleeger-agent \
-v fleeger-agent-data:/var/lib/fleeger \
-e FLEEGER_HUB_URL=https://your-hub.example.com \
--env-file fleeger-agent.env \
registry.netcode.dev/fleeger/spoke-agent:X.Y.Z
rm fleeger-agent.envX.Y.Z is your hub's release version, the one the Onboard panel's command
carries. The named volume keeps the bootstrapped credentials across restarts.
--restart unless-stopped starts the agent again after a crash, a failed first
boot, or a reboot of a host whose Docker daemon starts at boot; docker stop fleeger-agent keeps it stopped. Docker copies the env file into the
container's configuration when it creates it, so the file is not needed
afterwards. (If docker run fails, create the file again before retrying; if
it failed because a fleeger-agent container exists, docker rm -f fleeger-agent first.)
Same host as the hub?
localhostinside the container is the container itself, not your host, and the edge only resolves on the hub's Docker network. Attach to it and point at the edge, withfleeger-agent.envcreated and removed as above:docker run -d --restart unless-stopped --name fleeger-agent --network fleeger_default \ -v fleeger-agent-data:/var/lib/fleeger \ -e FLEEGER_HUB_URL=http://edge \ --env-file fleeger-agent.env \ registry.netcode.dev/fleeger/spoke-agent:X.Y.Z
Kubernetes
Use the Helm chart: fleeger-agent chart (a Deployment + a
small PVC for the creds), installed from the OCI registry at your hub's
release version (the Onboard panel fills --version in from the hub build):
printf 'Registration token: '; stty -echo; IFS= read -r FLEEGER_TOKEN; stty echo; echo
printf '%s' "$FLEEGER_TOKEN" | kubectl create secret generic fleeger-agent-token \
--from-file=registration-token=/dev/stdin --dry-run=client -o yaml | kubectl apply -f -
unset FLEEGER_TOKEN
helm install fleeger-agent oci://registry.netcode.dev/fleeger/charts/fleeger-agent \
--version 1.0.0-rc1 \
--set image.repository=registry.netcode.dev/fleeger/spoke-agent \
--set hub.url=https://your-hub.example.com \
--set existingSecret=fleeger-agent-tokenOr from a repository checkout, with fleeger-agent-token created as above and
the fleeger/spoke-agent:local image built from the checkout and loaded into
the nodes:
helm install fleeger-agent charts/fleeger-agent \
--set image.tag=local \
--set hub.url=https://your-hub.example.com \
--set existingSecret=fleeger-agent-tokenFor an agent monitoring the very cluster it runs in, add --set rbac.create=true
for read-only node/pod metrics via its ServiceAccount. See
Deploying Fleeger on Kubernetes.
Standalone (binary)
There's no separately-published binary artifact — only the container images are
built by CI (container images). Build the
spoke-agent binary from the repo:
cargo build -p spoke-agent --release # → target/release/spoke-agentThen write a config file and run it directly:
# spoke-agent.toml
hub_url = "https://your-hub.example.com"
registration_token = "<token>"
nats_creds = "/var/lib/fleeger/agent.creds"
spoke-agent --config spoke-agent.tomlEnv vars override the file, so the same binary works with either.
Dev / manual alternative
Running an agent by hand on the dev machine (no bootstrap):
- Mint credentials for the location:(
CONFIG_PATH=services/auth-svc/config.toml \ cargo run -p auth-svc -- mint-creds --location <location-id> > deploy/nats/auth/minted-<location-id>.credsdeploy/nats/auth/is gitignored — these are secrets.)<location-id>is the location's record id, not its display name. The command needs the hub database: it records the credential's user key in the revocation ledger before it prints the creds, so offboarding the location can revoke them. If it cannot connect or sign in to the database, or the database refuses the row, it exits non-zero and prints nothing; delete the empty file the redirect left behind. On a deployed hub, run it in the auth-svc container instead (minting by hand). - Point a spoke-agent config at that location and creds file
(
location,nats_creds,nats_url), then:cargo run -p spoke-agent -- --config <that-config>.toml
Verifying
- Dashboard → Locations: the card shows reachable with a recent "last seen".
- Any resources under the location start reporting; auto-discovered sub-resources (VMs, k8s nodes) appear as read-only rows.
- Still unreachable after a minute? Work through checking reachability.