Skip to content
k8s-lookout

Getting started

This section is for anyone starting from zero: you have a kubeconfig, maybe an AI agent, and you have never run lookout. By the end you will have the binary installed, real diagnostic output from a cluster you already have access to, and — if you take the later steps — a sentinel deployed in-cluster, opening incident sessions for your agent. The first useful command needs nothing deployed at all.

Remember the shape: one binary, lookout, used three ways — the CLI (one-shot diagnostic commands), the MCP server (lookout mcp, the same commands as MCP tools), and the sentinel (lookout watch, the optional in-cluster watcher). The path in is incremental — each step works without the next:

  1. Install — get the lookout binary on your workstation, and know which container image flavor a cluster deployment needs.
  2. First reads — the CLI against your current kubeconfig, nothing deployed. Start with lookout scan: no target, no flags, and it names what is broken.
  3. Tutorial — a ~20-minute end-to-end run on a disposable kind cluster: stage real failures, watch the sentinel open and close incidents.
  4. Deploy the sentinel — one kubectl apply -k from the shipped manifests, what each manifest is, the RBAC tiers, and the flags that matter.
  5. Connect to core-agent — the daemon contract: sessions, injects, per-incident vs shared routing.
  6. MCP setup — every read command as an MCP tool, for agent runtimes that cannot shell out.
  7. Integrations — beyond core-agent: the read path from any MCP client or shell-capable agent, and the watch path into any webhook receiver.

The two commands worth running first take no arguments and need nothing deployed — point them at a cluster you have never seen:

Terminal window
lookout scan     # what is broken right now
lookout audit    # what has no safety net, while it is still healthy

What lookout detects is the coverage map for both, and for the sentinel: one page per mode, listing everything each one looks for.

The Reference section is generated from the same declarations that produce --help — when this section links a flag or a command, the reference page is the authoritative surface.