kubeintellect 2.0.1

AI-powered Kubernetes management — local server and CLI

KubeIntellect

AI DevOps engineer for Kubernetes

Website · Live Demo · Docs · v1 (LibreChat backend)

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

---

Quickstart — Pick Your Path

Starting point	Path
Try it instantly — no install at all	Browser demo — open in browser, slower, read-only
Try it fast — no Docker, no cluster	A — kube-q CLI (read-only, one pip install)
Try it fast — no cluster, install Docker	B — create local cluster (~5 min, all features)
Have Docker, no cluster	pip install + kubeintellect init
Have an existing cluster	pip install + kubeintellect init
Want Docker Compose / production setup	Docker Compose

---

A — kube-q CLI (no install except pip)

Install only the thin CLI. kq defaults to https://api.kubeintellect.com — no --url needed.

pip install kube-q
kq --api-key ki-ro-dev

Read-only — the demo cluster is shared. Destructive ops are disabled. For full access use path B.

---

Browser demo (zero install)

No terminal, no install. Open kubeintellect.com/demo directly.

Slower than the CLI — the browser terminal shares a single hosted instance. Read-only access.

---

B — Create local cluster

Docker is the only prerequisite. kubeintellect init installs Kind, creates the cluster, deploys sample workloads, and starts a background service.

1. Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker

2. Install KubeIntellect

pip install kubeintellect

3. Run the wizard — answer Y to everything

kubeintellect init

The wizard:

• Asks your LLM provider (OpenAI or Azure) and API key
• Creates a local Kind cluster with sample workloads
• Optionally installs Prometheus, Grafana, and Loki
• Optionally deploys 5 broken-pod RCA scenarios to practise with
• Generates an API key and configures kq automatically
• Installs a systemd service so the server starts on every login

4. Open a new terminal

kq

No manual server start, no copy-pasting API keys.

---

C — Local install (have Docker or existing cluster)

pip install kubeintellect

kubeintellect: command not found / kq: command not found? pip installs scripts to ~/.local/bin which may not be on your PATH. Fix it permanently:

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

Prefer isolated install? pipx manages a private env automatically — no PATH fiddling:

pipx install kubeintellect   # apt install pipx  if missing

Ubuntu 22.04 ships Python 3.10. You need 3.12+:

sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt-get install -y python3.12 python3.12-distutils
python3.12 -m pip install kubeintellect

First-time setup — one command

kubeintellect init

The wizard will:

• Ask your LLM provider (OpenAI or Azure) and API key
• Offer to create a local Kind cluster with sample workloads
• Offer to install Prometheus, Grafana, and Loki for observability
• Offer to deploy broken-pod RCA scenarios to practise with
• Choose SQLite (default) or PostgreSQL for persistence
• Generate an API key and configure kq automatically
• Install a systemd service so the server starts on every login

After init completes, open a new terminal and run:

kq

That's it. No manual server start, no copy-pasting API keys.

What kubeintellect status shows

  Config:    ✓  ~/.kubeintellect/.env
  LLM:       ✓  azure / gpt-4o
  DB:        ✓  sqlite  ~/.kubeintellect/kubeintellect.db
  kubectl:   ✓  found
  Kube:      ✓  ~/.kube/config  context: kind-kubeintellect
  Auth:      ✓  enabled
    admin     ki-admin-xxxxxxxxxxxxxxxxxxxx   ← use this as KUBE_Q_API_KEY
  Prometheus:✓  http://172.18.0.2:30090  reachable
  Loki:      ✓  http://172.18.0.2:30100  reachable
  Grafana:   ✓  http://172.18.0.2:30080  reachable
  kube-q:    ✓  found

Database

Mode	When	Setup
SQLite	Default — local / testing	None — init sets it automatically
PostgreSQL	Production / team	Set DATABASE_URL in ~/.kubeintellect/.env

---

kube-q — Terminal Client

kube-q is the CLI that talks to KubeIntellect. Install it separately and point it at any running instance.

pip install kube-q
kq "why is my pod crashlooping?"

---

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

---

Other deployment options

Docker Compose (laptop / VM — no cluster required to run the server)

git clone https://github.com/MSKazemi/kubeintellect
cd kubeintellect
cp .env.example .env

Open .env and fill in three things:

# 1. LLM key (OpenAI or Azure)
OPENAI_API_KEY=sk-...          # or AZURE_OPENAI_API_KEY / AZURE_OPENAI_ENDPOINT

# 2. Database password
POSTGRES_PASSWORD=changeme     # use something stronger

# 3. Admin API key — generate one, then paste the same value as KUBE_Q_API_KEY below
KUBEINTELLECT_ADMIN_KEYS=ki-admin-$(openssl rand -hex 10)

docker compose up -d
pip install kube-q

# KUBE_Q_API_KEY = the value you set in KUBEINTELLECT_ADMIN_KEYS above
KUBE_Q_API_KEY=<your-admin-key> kq --url http://localhost:8000

Full guide: Deploy: Docker Compose

Other options

Option	When to use
Kind cluster	Local K8s dev with monitoring + Langfuse
Cloud / VM (Helm)	Production, AKS, or company cluster

Full guide: Quickstart

---

CLI reference

Command	Purpose
kubeintellect init	Setup wizard — LLM key, cluster, observability, kube-q, systemd service
kubeintellect serve	Start the API server (default: 0.0.0.0:8000)
kubeintellect status	Show config + connectivity for all components
kubeintellect set KEY=VALUE	Update a value in ~/.kubeintellect/.env
kubeintellect db-init	Apply schema to PostgreSQL
kubeintellect kind-setup	Create a Kind cluster + DNS config
kubeintellect service <action>	Manage the systemd background service (install / uninstall / start / stop / status / logs)

---

Docs

Topic	Link
All install options	Quickstart
pip — no cluster (quick try)	Install: no cluster
pip — existing cluster	Install: existing cluster
pip — local Kind cluster	Install: Kind
Docker Compose	Deploy: Docker Compose
Kind dev environment (repo)	Deploy: Kind
VM / AKS / cloud (Helm)	Deploy: cloud / Helm
All config options	Configuration reference
Security model	Security

---

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/
docs/
tests/

---

v1 (LibreChat backend)

The original KubeIntellect used a LibreChat frontend with a LangGraph multi-agent backend (Supervisor → specialized worker agents, HITL checkpoints, dynamic tool generation). It is preserved on the v1-legacy branch.

---

License

AGPL-3.0. Commercial licenses available — see LICENSE-COMMERCIAL.md.