Giving an agent a useful health check
Before an agent can help fix something, it needs a reliable way to see what is broken.
My homelab runs services on Kubernetes, with Flux applying the configuration I keep in Git. Checking its health means looking at several layers: the machines, the running workloads, and whether the configuration has actually been applied. I built one CLI to gather those observations and return structured results an agent can read.
The tool does not need a model to decide whether a read failed or a workload is ready. Those checks belong in code. The agent can use the resulting evidence to explain a problem and choose the next investigation, without having to reconstruct the same collection sequence every time.
- CollectMachines, workloads and configuration readiness
- SummarizeCounts, current issues and collection errors
- InvestigateThe agent interprets evidence and proposes next checks
- VerifyA fresh observation after any authorized repair
Three reports that mean different things
These are shortened, fictional results. Expand each one to see what an agent can conclude. Nothing here queries or changes my homelab.
All reads succeeded, with no detected issues
{
"healthy": true,
"complete": true,
"issues": [],
"collection_errors": []
}The tool found no problems in the resources it checked. That is useful evidence, but it does not prove every application works. A service could still return errors while its containers are ready.
A workload is repeatedly crashing
{
"healthy": false,
"complete": true,
"issues": [{
"resource": "pods",
"name": "example-worker",
"reasons": ["CrashLoopBackOff"]
}],
"collection_errors": []
}Collection succeeded and there is a current issue to investigate. The agent can propose looking at the failing workload’s logs or recent changes. This report alone does not tell it the root cause, and the health command does not restart anything.
The workload read timed out
{
"healthy": false,
"complete": false,
"issues": [],
"collection_errors": [{
"resource": "pods",
"reason": "timeout"
}]
}An empty issue list does not mean the system is healthy. The tool could not finish collecting evidence, so the result stays incomplete and does not report health. The agent should explain the gap and investigate or retry the failed read.
Keep the observations
The CLI can save a snapshot and summarize it again without contacting the cluster. That lets me reproduce what the tool saw and check the summarizer against the same inputs, instead of debugging against a system that has already changed.
A replay is historical evidence. After a repair, I need a fresh collection to know what changed. A stored snapshot cannot establish the current health of the cluster.
What the real tool collects
homelab-health reads nodes, pods, Flux Kustomizations and HelmReleases concurrently, with bounded query timeouts. It checks readiness, current container failures, node pressure and whether configuration generations have been reconciled.
The tool returns JSON and a nonzero exit code for unhealthy or incomplete results. It can save observations with --save-snapshot and replay them with --from-snapshot. Snapshots omit pod specifications, logs and raw messages, but retain resource names. I still treat them as infrastructure data, and the examples here are fictional.
Where the AI fits
I want the agent to spend its attention on the question the evidence raises: what changed, what should we inspect next, and how will we know a repair worked? Giving it one bounded tool for the exact collection work makes those questions easier to answer.