kubeintellect 2.0.0a1

AI-powered Kubernetes management — local server and CLI

KubeIntellect V2

AI-powered Kubernetes management. Natural-language interface to diagnose faults, query cluster state, and execute remediation — with human approval gating all destructive actions.

---

Quickstart

Fastest — pip install (no repo clone needed)

pip install kubeintellect
pipx install kube-q          # or: pip install kube-q

kubeintellect init           # interactive wizard: LLM, database, kubeconfig
kubeintellect serve          # auto-detects database; starts on http://localhost:8000

kubeintellect serve handles the database automatically:

• Postgres running locally → uses it
• Docker available, no Postgres → offers to start a container
• No Docker → falls back to SQLite (no extra setup needed)

Connect:

KUBE_Q_API_KEY=<admin-key> kq --url http://localhost:8000

If kubeintellect / kq are not found after install, add ~/.local/bin to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

---

Other deployment options

Option	When to use
Docker Compose	Laptop, no K8s cluster, full stack via Docker
Kind cluster	Local K8s dev with monitoring + Langfuse
Cloud / VM (Helm)	Production, AKS, or company cluster

Full guide: docs/quickstart.md

---

Architecture

kq (CLI)  ──► KubeIntellect API (FastAPI + LangGraph)
                │
                ├── Coordinator (GPT-4o)
                │     ├── simple query  → direct tool use → answer
                │     └── complex fault → fan-out to 4 parallel subagents
                │           ├── Pod subagent     (kubectl)
                │           ├── Metrics subagent (Prometheus / PromQL)
                │           ├── Logs subagent    (Loki / LogQL)
                │           └── Events subagent  (kubectl events)
                │
                ├── HITL gate — destructive ops pause for approval
                └── Role check — admin / operator / readonly enforced

Checkpointing: conversation state persists to PostgreSQL (production) or SQLite (local).

---

Authentication

Optional — if no keys are set, all requests are accepted.

# ~/.kubeintellect/.env  (written by kubeintellect init)
KUBEINTELLECT_ADMIN_KEYS=ki-admin-abc123
KUBEINTELLECT_OPERATOR_KEYS=ki-op-def456
KUBEINTELLECT_READONLY_KEYS=ki-ro-xyz789

Generate keys: openssl rand -hex 20

---

Repo layout

app/                        # core Python source (shared by all deployments)
deploy/
  docker-compose/           # monitoring configs (prometheus.yml, loki-config.yml, grafana)
  helm/
    kubeintellect/          # Helm chart + values for all environments
    langfuse/               # Langfuse LLM tracing chart
  kind/                     # Kind cluster configs
docker-compose.yaml         # laptop deployment entry point
scripts/
  kind/create-kind-cluster.sh
  vm/setup-nginx.sh, setup-tls.sh
tests/
docs/

---

kubeintellect kind-setup vs make kind-cluster-create

Two ways to get a local Kind cluster — pick based on who you are:

	kubeintellect kind-setup	make kind-cluster-create
Requires repo clone	No	Yes
Cluster config	Single-node	2-node, hot-reload mounts
Ingress	Basic nginx	Tuned for Kind dev
Cluster DNS auto-config	Yes — svc.cluster.local works from host	No
Monitoring / Langfuse	Via make targets (after cloning)	make monitoring-install / make langfuse-install
Who it's for	End users, ops teams	KubeIntellect developers

---

Docs

Topic	File
All install options	docs/quickstart.md
pip — no cluster (quick try)	docs/install-pip-no-cluster.md
pip — existing cluster	docs/install-pip-existing-cluster.md
pip — local Kind cluster	docs/install-pip-kind.md
Docker Compose	docs/deploy-docker-compose.md
Kind dev environment (repo)	docs/deploy-kind.md
VM / AKS / cloud (Helm)	docs/deploy-cloud.md
All config options	docs/configuration.md