Installing KubeIntellect

Installing KubeIntellect

Every install path, with what it actually gives you today. Verified 2026-08-10 in a clean virtualenv.

✅ PyPI is current — pip install is the recommended path again

All three distributions are published and match the source tree: kube-q 1.5.0, kubeintellect 2.2.0, ki-protocol 1.0.0. Every documented kq subcommand works from a plain pip install.

If you followed the old git+https://… workaround from this page, switch back:

pip install --upgrade kube-q     # 1.5.0

A git install pins you to a commit rather than a release, so you stop getting updates.

Gotcha worth keeping: kq <subcommand> --help exits 0 even on old builds, because argparse's -h fires before it validates the unrecognized positional. If you are checking whether a subcommand exists, test it without --help.

Which path should I use?

I want to…	Use	Status
Try it without installing anything	Browser demo	✅ works
Ask questions from my terminal	pip install kube-q	✅ 1.5.0, all subcommands
Run the server myself	pip install kubeintellect	✅ 2.2.0
Run the whole system	Container	✅ current (2.2.0)
Run it on a local cluster	Local Kind	✅ works
Track the development tip	From source	✅ unreleased changes
Install as a snap	—	❌ not published (why)

---

Browser — zero install

Open kubeintellect.com/demo. Read-only, shared demo cluster, no signup. The fastest way to see whether the idea is worth your time.

CLI from PyPI

pip install kube-q
kq --api-key ki-ro-dev          # defaults to https://api.kubeintellect.com

$ kq --version
kube-q 1.5.0
$ kq help                       # lists every subcommand

ki-protocol is pulled in automatically as a dependency — you do not install it yourself.

Verified 2026-08-10: export, postmortem, replay, findings, digest, detector, preference, completion and help all resolve on a clean virtualenv.

Server from PyPI

pip install kubeintellect
kubeintellect init          # setup wizard — writes ~/.kubeintellect/.env
kubeintellect kind-setup    # optional: a local Kind cluster to try it against
kubeintellect serve         # API server on :8000

From source — the development tip {#from-source-current}

Only needed if you want changes that are merged but not yet released:

pip install "kube-q @ git+https://github.com/MSKazemi/kubeintellect.git#subdirectory=v4/packages/kube-q"

This is not the recommended path. It pins you to whatever main looked like when you ran it, and you will not get updates. Prefer pip install kube-q unless you have a specific reason. Requires Python 3.12+.

Container — current {#container-current}

The images are built and pushed on every release tag and need no workaround:

docker run --rm -it ghcr.io/mskazemi/kubeintellect:2.2.0 --help

Available tags: latest, 2.2.0, 2.2, 2.0.2, 2.0.1, 2.0.0, 2.0, 2. Verified 2026-08-10 — the 2.2.0 manifest resolves.

Local Kind cluster {#local-kind}

Runs the whole system — server, agents, and a sample workload to break — on your laptop. Docker is the only prerequisite.

git clone https://github.com/MSKazemi/kubeintellect.git
cd kubeintellect
make kind-cluster-create      # one shared Kind cluster
make monitoring-install       # Prometheus + Grafana + Loki

Then follow v4/README.md for deploying the app itself.

Just want to run the tests / contribute?

You need none of the above — no cluster, no API key, no Docker:

git clone https://github.com/MSKazemi/kubeintellect.git
cd kubeintellect && make setup

See Your First Contribution.

---

Requirements

• Python 3.12+ for any Python install path. CI runs both suites on 3.12 and 3.13; the container runtime is python:3.13-slim.
• An OpenAI or Azure OpenAI API key to run your own server. Not needed for the hosted demo, and not needed to run the test suite. A local/self-hosted LLM path is #17.
• A Kubernetes cluster only if you want it to talk to your own cluster.

Something here wrong or out of date? That is a real bug — tell us.