Architecture
A control loop that reasons,
then acts with your approval.
KubeIntellect is not a chatbot bolted onto kubectl. It observes your cluster, reasons to a root cause, proposes a fix and — by default — runs it only after a human says yes.
This page covers v4, the current release you install today, and v1, the design published and peer-reviewed in the Journal of Grid Computing (2026). — plus the generations in between and the experimental v5 flags. All of them share one rule: reads run on their own, changes wait for you.
observe → reason → act (with approval) → verify
Two architectures, one question
From the published design to today’s release
Follow one question — “why is checkout-api crashing?” — through the peer-reviewed v1 architecture and the current v4 release, step through the whole v1 → v5 lineage, then see each difference credited to the version that made it.
Step 6 of 6
Approved, then answered
Once confirmed, the change runs and the Supervisor replies. In the peer-reviewed evaluation this design resolved 93% of 200 queries (186/200) and synthesized 63 of 77 novel tools (81.8%), in 7–10 s end to end.
v1, the published, peer-reviewed architecture: a LangGraph Supervisor routes a question to one of thirteen execution nodes at a time — twelve ReAct agents (Logs, Metrics, Lifecycle, RBAC, Execution, Infrastructure, ConfigMaps/Secrets, Code Generator, Dyn. Tools Executor, Security, Deletion, Apply) plus the DiagnosticsOrchestrator meta-node, which fans out log, metric and event sub-nodes in parallel. When no tool fits, the Code Generator writes one: AST check, 30-second test run, operator approval, registration. Writes wait at a human approval gate.
How it works today · v4
Six stages, one loop
What the current release does with a request. Each stage maps to a documented part of the open-source v4 code.
Ask — or let a detector ask
You ask in plain language. Or a detector — compiled checks that spend no LLM tokens — spots a known failure and opens the investigation itself. Its default autonomy, A1, is investigate and report: it never changes anything.
Start from a complete snapshot
Every turn begins with a parallel snapshot of all pods and Warning events. If a read fails or a listing is truncated, the snapshot is marked partial — and a partial picture is never reported as a healthy cluster.
Gather evidence in parallel
A lean coordinator answers simple questions directly with its tools. For a real fault it fans out four subagents at once — Pod, Metrics, Logs and Events — over kubectl, PromQL and LogQL.
Reach one diagnosis
The subagents’ findings merge into a single structured answer: the root cause, how confident the agent is, and the evidence behind it.
Pause for your approval
A proposed fix passes a role check (readonly, operator, admin, superadmin); Secrets and ServiceAccounts are blocked for every role. Every write or destructive kubectl command then waits at the approval gate, which is on by default.
Act, verify, record
Once you approve, kubectl runs and the coordinator checks the result with a fresh read. Every tool call, tool output and approval is appended to a hash-chained flight recorder, so the session can be replayed later with kq replay.
The published architecture · v1
What the paper describes, and what changed
The architecture peer-reviewed in the Journal of Grid Computing (2026) is v1: a LangGraph Supervisor that routes each turn to one of thirteen execution nodes — twelve ReAct agents (Logs, Metrics, Lifecycle, RBAC, Execution, Infrastructure, ConfigMaps/Secrets, Code Generator, Dyn. Tools Executor, Security, Deletion, Apply) plus the DiagnosticsOrchestrator meta-node, which gathers logs, metrics and events in parallel.
When no existing tool fits, v1’s Code Generator writes one at runtime: AST checks, a test run with a 30-second timeout, operator approval, then registration. On a live four-node cluster the published evaluation measured 93% query resolution (186/200), 81.8% tool-synthesis success (63/77), and 7–10 s end to end. Read the paper.
Most of the change happened in v2, the lean baseline: it kept parallel evidence gathering and the human approval gate and replaced the rest with one coordinator and four guarded tools. v4 is built on that v2 core. Why fewer agents worked better is in More agents is not more capability; the v4 results there are from a follow-up study that is not yet peer-reviewed.
Both live side by side in the public repository: v1/ for the paper, v4/ to run.
| v1 · published | v4 · current | Introduced | |
|---|---|---|---|
| Status | v1 · publishedPublished, peer-reviewed (Journal of Grid Computing, 2026); frozen in v1/ | v4 · currentCurrent release (kubeintellect 2.5.0); developed in v4/ | — |
| Orchestration | v1 · publishedLangGraph Supervisor routing each turn to one of 13 execution nodes | v4 · currentOne lean coordinator in a ReAct loop | Introduced: since v2 |
| Specialists | v1 · published12 ReAct agents + the DiagnosticsOrchestrator meta-node | v4 · current4 subagents — Pod, Metrics, Logs, Events | Introduced: since v2 |
| Parallelism | v1 · publishedInside the DiagnosticsOrchestrator only (logs, metrics, events) | v4 · currentA parallel snapshot every turn, then one 4-way fan-out for root cause | Introduced: since v2 |
| Tools | v1 · published~100+ Kubernetes-client tools, plus runtime tool synthesis by the Code Generator | v4 · current4 guarded tools: kubectl, Helm (read-only), Prometheus, Loki | Introduced: since v2 |
| Human approval | v1 · publishedWrites confirmed; Apply and generated code stop at a checkpoint | v4 · currentEvery write or destructive kubectl pauses — on by default | Introduced: every version |
| Access control | v1 · publishedOne shared ServiceAccount, read-only verbs by default | v4 · currentRole tiers enforced in the tool; Secrets and ServiceAccounts always blocked | Introduced: since v2, hardened in v4 |
| Partial snapshots | v1 · published— | v4 · currentA failed or truncated read is never reported as a healthy cluster | Introduced: v4 |
| Beyond a single request | v1 · published— | v4 · currentZero-token detectors that open investigations (A1), and a hash-chained flight recorder | Introduced: new in v4 |
The lineage · v1 → v5
Five generations, kept side by side
The repository keeps every generation, because the differences between them are the result. v1 → simplify → v2 → reframe → v3 → productionize → v4 → design forward → v5. Only v1 is peer-reviewed; v4 builds on v2, not on v3.
- v1Legacy · published, peer-reviewed
Capability-maximal
LangGraph Supervisor over 13 execution nodes, runtime tool synthesis, ~100+ Kubernetes-client tools. The architecture in the paper.
v1/ on GitHub - v2Baseline
Lean baseline
One coordinator over 4 guarded tools, a 7-layer kubectl guard, a parallel snapshot, a 4-subagent root-cause fan-out, role tiers and an evaluation harness.
v2/ on GitHub - v3Experimental
Framework-delegated
The v2 behaviour run by the DeepAgents framework: a virtual filesystem, visible plans, task() delegation to five specialists. Not carried forward.
v3/ on GitHub - v4Current release
Platform
The v2 core plus feature-flagged layers: detectors that open investigations, a memory hierarchy, a hash-chained flight recorder, autonomy levels.
v4/ on GitHub - v5Experimental · off by default
Design tier
Not a release: designed slices that live inside v4 behind 60 flags and settings, every slice off by default and 25 not wired yet. All off, the server is identical to v4.
v5 flags on GitHub
Why it’s different
Reasoning plus execution — not chat
It acts, behind a gate
It runs real kubectl, PromQL and LogQL against the live cluster and can apply the fix it proposes — after a role check and your explicit approval.
Parallel evidence, one diagnosis
Four subagents gather pod state, metrics, logs and events at the same time; the coordinator turns them into one root cause with its evidence.
Guardrails in the tool, not the prompt
Role tiers, protected namespaces and always-blocked Secrets are enforced before a command reaches the cluster. A partial snapshot is never read as “healthy”.
It watches, and keeps a record
Detectors open investigations without being asked — report-only by default — and a hash-chained flight recorder makes every session replayable.
Who it’s for
Built for the people on call
DevOps engineers
Troubleshoot faster, ship deployments, and automate the repetitive cluster work — without context-switching into five kubectl tabs.
SREs
Cut incident MTTR with automatic root-cause analysis and reliable, approval-gated remediation during on-call.
Platform teams
Give every engineer a safe, natural-language front door to the cluster, with destructive actions always behind a human gate.
FAQ
Common questions
Is KubeIntellect just a chatbot wrapped around kubectl?
No. It gathers live evidence itself — kubectl, PromQL against Prometheus, LogQL against Loki — reasons over it to a root cause, proposes a concrete fix, and can run it. Every change it proposes passes a role check and then waits for your approval.
Does KubeIntellect change my cluster automatically?
Not by default. Reads run automatically; any write or destructive kubectl command pauses at a human-in-the-loop approval gate, which is on by default. Detectors can open investigations on their own, but at the default autonomy level (A1) they only investigate and report. Auto-fix exists only for playbook and namespace pairs you explicitly allowlist, and that list starts empty.
Which architecture does the peer-reviewed paper describe?
The paper in the Journal of Grid Computing (2026) describes v1: a LangGraph supervisor routing to thirteen execution nodes — twelve ReAct agents plus a DiagnosticsOrchestrator meta-node — with a Code Generator that synthesizes new tools at runtime. The current release, v4, is a deliberately different, leaner system; its results are not part of that peer review.
Does the current version still generate tools at runtime?
No. Runtime tool synthesis is part of the published v1 architecture, where the Code Generator succeeded on 63 of 77 novel requests (81.8%) in the peer-reviewed evaluation. Since v2 it has been replaced by four guarded tools — kubectl, read-only Helm, Prometheus and Loki — so every action goes through the same checks; v4 keeps them.
What are v2, v3 and v5?
The repository keeps every generation side by side. v2 is the lean baseline that introduced the coordinator, the four guarded tools and the four-subagent fan-out; v4 is built on it. v3 was an experiment that ran the same behaviour on the DeepAgents framework and was not carried forward. v5 is a design tier: experimental flags inside v4, off by default — not a release.
Which Kubernetes clusters does it support?
It connects to an existing cluster through your kubeconfig. Continuous integration runs on Kind, and community members have verified the install on Amazon EKS, k3s/k3d and OpenShift/OKD. Other conformant clusters are expected to work but are not yet independently verified.
See the loop in action
Watch the recorded demo, or run it on your own cluster in minutes.