Docs · Your machines

Health and diagnostics

Five commands answer five different questions. Using the wrong one is the commonest reason a real problem looks invisible.

Which command answers which question#

doctor is the one to start with. It is read-only, it names problems in typed codes, and every result that is not a pass carries something to do about it.

nodeau doctor#

nodeau doctor
nodeau doctor --json          # every result, code, explanation and remedy
nodeau doctor --host-only     # this machine only, without contacting the cluster
nodeau doctor --node nodeau-c # one machine, plus installation-wide checks

Every check is read-only. Doctor never installs, configures, mounts, starts or stops anything; it only looks.

Two halves:

• The host — is this machine capable of running Nodeau: operating system, processor, memory, whether it is bare metal, storage safety, the state directory, Secure Boot, the GPU on the PCI bus, the driver, VRAM, network.
• The installation — is Nodeau itself working: its control plane, the agent on each machine, whether every GPU report is fresh enough to schedule against, whether the models on disk still verify, and what your services and batch jobs are doing.

Exit 0 everything passed or only warnings · 1 something failed · 2 called wrongly.

Doctor codes#

Stable, machine-readable, and the same in --json as in the human report.

Reaching the cluster

Hardware

Models

Workloads

Local endpoints

Account and plan

macOS

nodeau health#

nodeau health
nodeau health --json
nodeau health history --machine nodeforge --since 6h

The current state of every machine — processor, memory, storage and network — alongside the GPU readings already there, together with anything that needs attention.

Every reading was taken by the machine it describes, and stays on your own hardware. Telemetry is not sent to Nodeau Cloud, and there is no field for it in the protocol that talks to Nodeau Cloud at all.

Missing is not zero#

A value shown as "not collected" is missing, which is a different thing from zero. A card reporting 0% utilisation is idle; a card Nodeau could not read is unknown, and the two must never look the same.

health history follows the same rule: an interval with no observations is absent rather than zero, so a gap in the output is a gap in what was observed. Nodeau does not fill one in.

history flags#

Retention#

24 hours, uniformly. It is not a plan difference, and no plan gets more.

History lives in the Kubernetes datastore — which is the control-plane machine's disk. It is not replicated anywhere. If that disk is lost, the history goes with it.

What health does not do#

• No disk health and no SMART. Nodeau reads no drive attribute. It reports how full a filesystem is, and says so. It will not tell you a disk is failing.
• No per-process CPU or memory, no process list, no command lines, no connection table.
• No telemetry to Nodeau Cloud. The machines appear in the hosted console; these readings do not.
• No external alert delivery. No email, no webhook, no pager.
• Not qualified on Apple Silicon.

Alerts#

The controller reconciles a small set of conditions and reports what needs attention:

An alert has three states:

Only Active is counted anywhere — no badge, tile or nodeau health line moves for a Pending alert. That is what makes the third state additive rather than a claim.

nodeau status#

nodeau status

Nothing here is read from a cache. The workload state comes from the cluster, the endpoint state from the service manager, and "answering" from an actual connection to the port — so a stale record cannot make this report something that is not true.

It also lists anything that makes a model reachable from your network, if something on the machine does. Nodeau does not create those, and saying so is the point.

nodeau ps#

nodeau ps            # everything holding a GPU
nodeau ps --all      # including finished batch jobs
nodeau ps -A         # across all namespaces

Services and batch jobs alike, with where each one is and what it is doing.

nodeau logs#

nodeau logs qwen-local -f
nodeau logs my-batch
nodeau logs --system nodeau-controller

Nodeau's own components are under --system; everything else is looked up in your workload namespace.

Prompts, completions and batch records are never written to a log, so they cannot appear here.

The local dashboard#

nodeau dashboard

The same information in a browser: hardware, models, running services, alerts and plan. Bound to loopback, protected by a token, compiled into the binary, and it works with no internet connection at all.

It is read-only apart from one action — it can stop a batch job.

Documentation for the current published build, the beta channel. Something here wrong or missing? Tell us — a report from a machine we have never seen is the most useful thing we get.