Documentation
Get started with KubeIntellect
KubeIntellect is a two-component system: an AI inference backend that runs in the cloud, and a CLI you install locally. Together they let you debug and manage Kubernetes clusters in plain English — from your own terminal.
Overview
You keep working from your terminal. The CLI sends your question to the inference backend, which reasons over live cluster evidence and proposes an answer or a fix — and pauses for your approval before it changes anything. Here is how the pieces fit together.
Your Machine
kube_q CLI
pip install kube_q
KubeIntellect
AI inference backend
api.kubeintellect.com
Your Cluster
via kubeconfig
stays local · read-only
Your kubeconfig never leaves your machine. Queries go to the inference backend; results come back to your terminal.
Want the internals — the supervisor, the specialized agents, and the approval gate? Read the architecture →
Components
Two repositories, two roles. The backend is hosted for you; the CLI is the only thing you install.
KubeIntellect
AI Backend
The inference engine. It reasons over your cluster state, correlates logs and events, generates diagnoses, and synthesises kubectl commands. Runs at api.kubeintellect.com — you don't need to deploy anything.
- ▸Reasoning across logs, metrics, events, and RBAC
- ▸Full Kubernetes API coverage — pods, deployments, RBAC, events
- ▸Dynamic tool synthesis per query
- ▸Human-in-the-loop approval for all write operations
kube_q
CLI Client
The terminal client. Install it on your laptop via pip, point it at your kubeconfig, and connect to the KubeIntellect backend. No browser required — everything happens in your terminal.
Install
- ▸Works with any kubeconfig — local, EKS, GKE, AKS, bare-metal
- ▸Connects to api.kubeintellect.com — no local model needed
- ▸Interactive terminal UI with approval prompts
- ▸Requires Python 3.8+
Quickstart
From install to your first fix in four steps. Everything runs in your own terminal.
Install the CLI
Install kube_q from PyPI. Requires Python 3.8+.
Connect your cluster
Point kube_q at your kubeconfig. Read-only by default — no cluster-admin required.
Ask a question
Type your question in plain English. KubeIntellect reasons over your cluster state and returns a diagnosis.
Approve the fix
Every write, delete, or exec operation pauses for your explicit approval before anything runs.
Concepts
A few ideas that explain how KubeIntellect goes from a plain-English question to a concrete, verifiable action.
Two-component system
A cloud inference backend does the reasoning; a local CLI (kube_q) does the talking to your cluster. You install only the CLI.
Full API coverage
Read, write, exec, and delete across the Kubernetes API — pods, deployments, RBAC, events. KubeIntellect can act on findings, not just describe them.
Dynamic tool synthesis
When no existing tool fits a query, a code-generator writes a new one at runtime, so the system is never boxed in by a fixed automation catalog.
Workflow memory
Context is carried across multi-step operations, so a diagnosis and its follow-up fix stay connected within a session.
Safety & human-in-the-loop
KubeIntellect can act, not just explain — which is exactly why every risky action stops for a human.
Read is automatic. Write is not.
Read-only diagnostics — logs, events, configs, RBAC — run automatically so you get an answer fast. But any write, delete, or exec operation, and the registration of a newly generated tool, pauses at an approval gate. You see the exact command before it runs and confirm with [y/N].
Your kubeconfig stays on your machine, and the CLI connects read-only by default — no cluster-admin required to get started.
CLI reference (kube_q)
The core commands you'll use day to day. See the full kube_q reference for every flag and option.
Install
Install the CLI from PyPI (Python 3.8+).
Connect
Point kube_q at your kubeconfig — read-only by default.
Ask
Ask a question in plain English and get a diagnosis.
Links & references
Full API references, plus deeper reading on how KubeIntellect works and where it came from.
Architecture →
The control loop, the specialized agents, dynamic tool synthesis, and the approval gate.
Research →
The research behind KubeIntellect, the evaluation, and how the project has evolved.
Need the full reference?
Complete API reference, configuration options, and advanced usage guides.