Documentation

Install KubeIntellect and the kq CLI

KubeIntellect is a two-component system: an AI backend (the KubeIntellect server) and a CLI you install locally. Both install with one pip command and run on your own infrastructure, with your own LLM key — so you debug and manage Kubernetes in plain English from your own terminal. No cluster yet? The setup wizard can create a local Kind cluster for you.

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

kq CLI

pip install kube-q

KubeIntellect

AI backend server

self-hosted · your LLM key

Your Cluster

via kubeconfig

stays on your server · RBAC-scoped

Self-hosted, your kubeconfig stays with the server you run; questions and the cluster evidence needed to answer them go to the LLM provider you configure.

Want the internals — the coordinator, its parallel subagents, the approval gate, and the published v1 design? Read the architecture →

Components

Two components, two roles. You run the backend next to your cluster; the CLI is how you talk to it.

KubeIntellect

AI Backend

The inference engine. It reasons over your cluster state, correlates logs and events, generates diagnoses, and synthesises kubectl commands. Self-host it next to your cluster with pip install kubeintellect, Docker Compose, or Helm — it runs on your infrastructure with your own LLM key.

  • ▸Reasoning across logs, metrics, events, and RBAC
  • ▸kubectl, read-only Helm, Prometheus and Loki as guarded tools
  • ▸Four parallel subagents for root-cause analysis
  • ▸Human-in-the-loop approval for all write operations
Full DocumentationGitHub

kube-q (kq)

CLI Client

The terminal client. Install it on your laptop via pip and point it at a KubeIntellect server you run. No browser required — everything happens in your terminal.

Install

$pip install kube-q
  • ▸Talks to any KubeIntellect server you run, local or remote
  • ▸Configured for you by kubeintellect init — no local model needed
  • ▸Interactive terminal UI with approval prompts
  • ▸Requires Python 3.12+
Full DocumentationGitHub

Quickstart

From install to your first fix in four steps. Everything runs in your own terminal. To run the server for your own cluster (pip, Docker Compose, or Helm), follow the self-hosting quickstart.

01

Install KubeIntellect

Install the KubeIntellect server from PyPI. It also installs kube-q, which provides the kq command. Requires Python 3.12+.

$pip install kubeintellect
02

Run the setup wizard

kubeintellect init asks for your OpenAI or Azure OpenAI key, uses your kubeconfig — or creates a local Kind cluster, so you can try it on a laptop in minutes — generates your API key, and configures kq for you.

$kubeintellect init
03

Ask a question

Type your question in plain English at the kq prompt, or run a one-shot query with -q. KubeIntellect reasons over the cluster state and returns a diagnosis.

$kq -q "Why is my payment-service pod crashing?"
04

Approve the fix

By default, every write, delete, or exec operation pauses for your explicit approval before anything runs; auto-approve is an explicit operator opt-in for test environments. The Helm chart's default RBAC is read-only.

✋ Approval required — Proposed: kubectl set image deployment/payment-service ... HITL> /approve # or /deny to cancel

Concepts

A few ideas that explain how KubeIntellect goes from a plain-English question to a concrete, verifiable action.

Two-component system

The KubeIntellect server does the reasoning and runs kubectl against the cluster it is configured with; the kq CLI is the terminal client you talk to it through. You run the server yourself, next to your own cluster, with your own LLM key.

Acts, behind a gate

It reads and, with your approval, changes the cluster through kubectl — pods, deployments, events — under the role of the key you use. KubeIntellect can act on findings, not just describe them.

Parallel evidence

A lean coordinator answers simple questions directly; for a real fault it fans out four subagents — Pod, Metrics, Logs, Events — and merges their findings into one diagnosis. (Runtime tool synthesis belongs to the published v1 architecture, not the current release.)

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 pauses at an approval gate, and Secrets stay blocked for every role. You see the exact command before it runs and confirm at the HITL> prompt with /approve (or /deny).

Self-hosted, your kubeconfig stays with the server you run. The Helm chart grants read-only RBAC by default (write and exec verbs are opt-in), read-only API keys can only query, and no cluster-admin is required to get started.

CLI reference (kq)

The core commands you'll use day to day. See the full kube-q reference for every flag and option.

Install

Install the CLI on its own from PyPI (Python 3.12+), e.g. on a laptop that talks to a remote server. The command is kq. (pip install kubeintellect already includes it.)

$pip install kube-q

Open the interactive prompt

After kubeintellect init, kq is already pointed at your server with your key.

$kq

Connect to your own server

Point kq at a KubeIntellect server you run (kubeintellect init sets this up for you; kubeintellect status shows the key).

$kq --url http://localhost:8000 --api-key YOUR_KEY

Ask

Run a one-shot question in plain English and get a diagnosis.

$kq -q "Why is my payment-service pod crashing?"