Quickstart

Install Kopilot from source, point it at an LLM provider, and run your first task against a cluster you can safely experiment with.

Naming, once and for all: the product is Kopilot; the Python package and Kubernetes API group are named kubedevaiops. After installation, both the kopilot and kubedevaiops commands work and do the same thing. This documentation uses kopilot.

Prerequisites

Install from source

git clone https://github.com/kopilot-ai/kopilot
cd kopilot
pip install -e .

There is no PyPI release yet; installing from a clone is the supported path today. Container images are published by CI to GHCR — see Deployment.

Configure

Kopilot reads environment variables, optionally from a .env file in the working directory. Start from the annotated example: 

cp .env.example .env

A minimal .env for a local Ollama setup:

LLM_PROVIDER=ollama
LLM_MODEL=gpt-oss:20b
OLLAMA_BASE_URL=http://localhost:11434

# Required outside local development. Without it the API is open
# and the server logs a warning on startup.
API_AUTH_TOKEN=change-me

Or, to use a hosted provider instead:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

The model is selected per provider (ANTHROPIC_MODEL, OPENAI_MODEL, GEMINI_MODEL, …); for Ollama the model comes from the generic LLM_MODEL variable. The full list of variables and defaults is in Configuration.

Run a first task

kopilot ask "Which pods in this cluster are not ready, and why?"

The supervisor routes the question to a skill sub-agent (here, most likely troubleshooting), which runs read-only kubectl commands and returns findings with evidence. Read-only investigation never requires approval.

Run the server

kopilot serve starts the REST API together with the Kopf operator, the Kubernetes event watcher, and the Slack bot (if configured): 

kopilot serve

Then, from another terminal:

curl -s localhost:8080/health
curl -s -X POST localhost:8080/tasks \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarize resource usage in the default namespace"}'

The response contains task_id, answer, risk_level, elapsed_ms, and attempts.

Try the approval workflow

Ask for something destructive and Kopilot will refuse to execute it, registering a pending approval instead and reporting the approval id in its answer: 

curl -s -X POST localhost:8080/tasks \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Delete the deployment named demo in the default namespace"}'

List the pending queue and decide:

curl -s -H "Authorization: Bearer $API_AUTH_TOKEN" \
  "localhost:8080/approvals?status=pending"
curl -s -X POST "localhost:8080/approvals/<approval-id>/approve" \
  -H "Authorization: Bearer $API_AUTH_TOKEN" \
  -H "X-Kopilot-Operator: alice"

Approvals are single-use, apply to the exact command, and expire after 10 minutes. When the agent retries the command after approval, it executes. The queue is in-memory: it does not survive a restart.

Next steps