Skip to content
k8s-lookout

k8s-lookout

k8s-lookout helps AI troubleshooting agents see what is happening inside a Kubernetes cluster. It answers the questions an investigation runs on — what is broken, what changed, who is affected — in a form small enough and safe enough to hand straight to a language model, and it can watch the cluster and tell your agent the moment something starts going wrong.

The problem

Section titled “The problem”

An AI agent troubleshooting a cluster is only as good as what it can see. Point it at raw kubectl output and it drowns: describing one crash-looping payment service takes a dozen slow commands, most of the output is routine noise, and some of it — environment variables, mounted Secrets — is exactly the material that must never reach a model. And even a well-equipped agent only investigates when asked. Nobody tells it the moment a bad image tag ships or a certificate is three days from expiring.

What’s in the box

Section titled “What’s in the box”

Everything ships as one binary, lookout, used three ways — each one works without the others:

  • The lookout CLI — one-shot diagnostic commands (lookout health, lookout triage delta, lookout bundle, …) that you or a shell-capable agent run against your current kubeconfig. Nothing gets deployed; this is the two-minute starting point.
  • The MCP server — lookout mcp exposes every one of those commands 1:1 as MCP tools, for agent runtimes that speak MCP instead of shelling out. Same checks, same output, same sanitizer.
  • The sentinel — lookout watch, an optional daemon you deploy into the cluster. It watches for trouble as it develops — a stalling rollout, memory climbing toward a limit, a certificate counting down — and opens an incident session for your agent, often before users notice anything.

lookout never writes to your cluster. It reads, watches, and reports; any fix goes through your agent’s own approval process.

A taste

Section titled “A taste”

“Any issues with this cluster?” is one command:

Terminal window
lookout health
Terminal window
kind=health.category severity=info category=nodes status=healthy
kind=health.category severity=warning category=crashloops status=degraded total=8 top="pod.restarts agent-sandbox-system/agent-sandbox-controller-7c69875fcc-n7xms; pod.restarts kube-system/coredns-7d764666f9-g82j9; …"
kind=health.category severity=info category=rollouts status=healthy
scanned=16 findings=18 elapsed=537ms

(Real output against a kind cluster, abridged.) Every category reports, healthy resources stay quiet, and the last line always says what was scanned — so “all clear” is never ambiguous silence.

Where next

Section titled “Where next”
  • Just want to point it at a cluster? → Getting started — install the CLI and run the first commands, nothing deployed.
  • Want a 20-minute guided demo? → Tutorial — a disposable kind cluster, staged failures, and the full detect → enrich → resolve loop.
  • Are you an AI agent setting this up? → For AI agents — the dense, copy-runnable version, plus llms.txt.
  • Want to know what it actually detects? → What lookout detects — one coverage page per mode: scan for incidents, audit for posture, the sentinel for what only a resident process can see.
  • Want incidents to open themselves? → What the sentinel watches — what it monitors out of the box and what you can turn on, then deploy it with one kubectl apply.
  • Wiring up an agent? → MCP setup for any MCP-speaking runtime, or Integrations for shell-capable agents and webhook receivers.
  • Want to understand how it works? → Concepts — the mental model behind the commands.

Container images live at ghcr.io/go-steer/lookout; everything works out of the box with core-agent. The full command surface is in the Reference, and day-2 sentinel material in Operations.