Kobi
Enabling Kobi
Turn Kobi Copilot on with your own key — the copilot.* Helm values, the KUBEBOLT_AI_* environment variables, and the Configuration page that overrides both.
On this page
Kobi Copilot ships in every edition but starts off when you self-host. This page is how you turn it on. What Kobi can do once it is on — the tools, the providers, the MCP server — is Kobi Copilot.
On KubeBolt Cloud there is nothing to configure. The AI is platform-managed: the provider, the model and the key are ours, and usage draws from your plan’s credits, which is also the unit the app shows it in. Kobi is available from the Free plan. An organization admin can still turn Kobi’s proposals off, or only the destructive ones, and set the tool-call cards and the action timeout in Administration › AI & Autopilot › Kobi Copilot. Stop reading here unless you self-host.
The switch is the API key
Kobi is on whenever a provider key is configured — either KUBEBOLT_AI_API_KEY
on the API container or a key saved in Administration → AI (Kobi) →
Configuration. With neither, Kobi is off. There is no separate “on” flag at
runtime — copilot.enabled in the chart only decides whether the chart renders
the AI environment block at all.
KubeBolt is bring-your-own-key when you self-host. You pay your provider directly; KubeBolt has no AI billing and never sends your key anywhere except the provider endpoint you configured. What Kobi sends that provider is in What reaches the model.
With Helm
The chart’s copilot block defaults to enabled: false. Store the key in a
Secret rather than passing it inline:
kubectl create secret generic kubebolt-copilot-key -n kubebolt \
--from-literal=api-key=$ANTHROPIC_API_KEY
helm upgrade --install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --create-namespace \
--set copilot.enabled=true \
--set copilot.provider=anthropic \
--set copilot.existingSecret=kubebolt-copilot-key
The full block, with its defaults:
copilot:
enabled: false # must be true or no AI env is rendered at all
provider: anthropic # anthropic | openai
model: "" # empty = the provider's default
baseUrl: "" # full endpoint URL, used as-is
maxTokens: "" # empty = per model (see below)
cacheTtl: "" # Anthropic prompt cache: empty = 1h, "5m" = the API default
apiKey: "" # inline key — prefer existingSecret
existingSecret: "" # Secret containing the key under `api-key`
fallback:
enabled: false
provider: "" # empty = same as the primary
model: ""
baseUrl: ""
apiKey: ""
existingSecret: ""
escalation:
model: "" # see "The escalation model" below
Only anthropic and openai are valid providers; any other value fails.
Every OpenAI-compatible API — Azure OpenAI, xAI, DeepSeek, Groq, Mistral,
Ollama, vLLM — uses openai with a baseUrl. The base URL is the full
request URL and is used verbatim: for OpenAI-compatible endpoints it must end
in the chat-completions path (http://ollama.internal:11434/v1/chat/completions,
not …/v1).
existingSecret wins over apiKey. The Secret must carry the key under
api-key; the chart mounts it as an env var, so the value never appears in
your values file or in helm get values.
The chart has values only for the settings above. The others in the next
section — the action switches, max tool steps, tool-call cards, the action
timeout and conversation memory — go through extraEnv, or are set on the
Configuration page:
extraEnv:
- name: KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED
value: "false"
With environment variables
Docker Compose and bare-binary installs set the same variables directly. Copy
deploy/.env.example to deploy/.env and fill them in.
| Variable | Helm value | Default | What it does |
|---|---|---|---|
KUBEBOLT_AI_API_KEY | copilot.existingSecret / copilot.apiKey | — | Your provider key. Empty disables Kobi. |
KUBEBOLT_AI_PROVIDER | copilot.provider | anthropic | anthropic or openai (openai covers every OpenAI-compatible API) |
KUBEBOLT_AI_MODEL | copilot.model | claude-haiku-5-5 (anthropic) · gpt-4o (openai) | Model id |
KUBEBOLT_AI_BASE_URL | copilot.baseUrl | provider default | Full endpoint URL, used as-is (e.g. …/v1/chat/completions) |
KUBEBOLT_AI_MAX_TOKENS | copilot.maxTokens | per model | Ceiling per response. Unset, it is 16384 where reasoning counts against it (Claude, OpenAI reasoning models) and 4096 elsewhere. Set it only to override |
KUBEBOLT_AI_CACHE_TTL | copilot.cacheTtl | 1h | Anthropic only: how long the cached system prompt and tool definitions live. 5m returns to the API default, cheaper only when questions are rare |
KUBEBOLT_AI_MAX_ROUNDS | extraEnv | 20 | Tool-calling rounds per answer, clamped to 2–40. On the last one Kobi summarizes what it found instead of failing |
KUBEBOLT_AI_SHOW_TOOL_CALLS | extraEnv | true | Render each tool call as a card in the panel |
KUBEBOLT_AI_ACTIONS_ENABLED | extraEnv | true | Master switch for the propose_* action tools |
KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED | extraEnv | true | Gates delete and scale-to-zero specifically |
KUBEBOLT_AI_ACTION_PROGRESS_TIMEOUT | extraEnv | 90s | How long an approved action’s rollout is followed before Kobi is asked why it stalled. Minimum 10s |
The fallback (KUBEBOLT_AI_FALLBACK_*) and escalation
(KUBEBOLT_AI_ESCALATION_*) variables are below. Conversation-memory
variables (KUBEBOLT_AI_AUTO_COMPACT and friends) are documented in
Kobi Copilot, and the conversation
history ones (KUBEBOLT_COPILOT_CONVERSATION_*) in
Conversations.
Docker Compose passes only the variables its file lists. The stock
deploy/docker-compose.yml forwards the key, provider, model, base URL,
max tokens, cache TTL, max rounds, tool-call cards, action timeout, and the
fallback and escalation variables. The two action switches and the
conversation-memory variables are not forwarded: set them on the
Configuration page, or add them to the api service’s environment.
Set KUBEBOLT_AI_ACTIONS_ENABLED=false to run Kobi as a read-only advisor, or
only KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED=false to keep every proposal but
deletes and scale-to-zero. The first removes the proposal tools from what the
backend offers the model; the second also makes the action endpoints reject a
Kobi-proposed delete or scale-to-zero with a 403. See
Actions & Governance.
Provider endpoints
Anthropic and OpenAI need no base URL. Everything else uses
KUBEBOLT_AI_PROVIDER=openai and its full chat-completions URL:
| Provider | Base URL |
|---|---|
Anthropic (anthropic) | built in: https://api.anthropic.com/v1/messages |
| OpenAI | built in: https://api.openai.com/v1/chat/completions |
| Azure OpenAI | https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<version> |
| xAI | https://api.x.ai/v1/chat/completions |
| DeepSeek | https://api.deepseek.com/v1/chat/completions |
| Groq | https://api.groq.com/openai/v1/chat/completions |
| Mistral | https://api.mistral.ai/v1/chat/completions |
| OpenRouter | https://openrouter.ai/api/v1/chat/completions |
| Ollama | http://<host>:11434/v1/chat/completions |
| vLLM | http://<host>:8000/v1/chat/completions |
- The
openaiadapter sends the key asAuthorization: Bearer <key>. Azure OpenAI’sapi-keyheader is not sent: a resource that only accepts it needs a gateway in front. The deployment in an Azure URL decides the model; setKUBEBOLT_AI_MODELto the model behind it anyway, because KubeBolt uses it for the context window and the cost estimate. - The model must support tool calling — Kobi reads every piece of cluster data
through tools. vLLM needs
--enable-auto-tool-choiceand a tool-call parser. - On any endpoint other than OpenAI itself, set
KUBEBOLT_AI_COMPACT_MODELto a cheap model that endpoint serves: the default,gpt-4o-mini, exists only at OpenAI. - OpenAI’s Pro models are not supported: OpenAI serves them only through
/v1/responses.
The fallback provider
The fallback answers when the primary fails on a recoverable error — 429, 5xx, 404 (model or endpoint unavailable for your account), or a network fault. Any other 4xx from your provider (bad key, bad request) is propagated to you instead, because retrying it would fail the same way.
It can be a cheaper model from the same provider, a different provider, or a
self-hosted endpoint. What arms it is its own key: with Helm, set
copilot.fallback.enabled=true plus a key; without Helm, set
KUBEBOLT_AI_FALLBACK_API_KEY. The other three variables
(KUBEBOLT_AI_FALLBACK_PROVIDER, _MODEL, _BASE_URL) are optional; provider
defaults to the primary’s.
copilot:
enabled: true
provider: anthropic
existingSecret: anthropic-key
fallback:
enabled: true
provider: openai
existingSecret: openai-key
model: gpt-4o-mini
When an answer came from the fallback, the chat panel marks it with an “Answered by the fallback model” badge, so a misconfigured primary is never silently masked.
The escalation model
Kobi can run on a small model and move to a stronger one, for the rest of the
conversation, the first time the investigation leaves the selected cluster: a
cloud connector call, or a get_external_connections
answer that points at a cloud dependency one of your connectors can read. A
conversation opened by a switch to another cluster starts on the escalation
model. Questions inside one cluster stay at the small model’s cost, and each
model is priced at its own rate in the usage page.
copilot:
enabled: true
provider: anthropic
model: claude-haiku-5-5
existingSecret: anthropic-key
escalation:
model: claude-sonnet-5-5
With Helm it shares the primary’s provider and key. Without Helm, set
KUBEBOLT_AI_ESCALATION_MODEL, and KUBEBOLT_AI_ESCALATION_PROVIDER, _API_KEY
and _BASE_URL if it runs elsewhere; with the same provider, the key and base
URL default to the primary’s. An escalation model equal to the primary does
nothing. In the UI it is Escalation model, in the primary provider’s card.
In the UI
Administration → AI (Kobi) → Configuration (/admin/ai, Admin role) edits
the same settings without a redeploy:
| Card | Fields |
|---|---|
| Primary provider | Provider, Model, Escalation model, API key, Base URL |
| Fallback provider | Provider, Model, Fallback API key, Fallback base URL |
| Behavior | Max tokens, Tool calls, Kobi actions, Destructive actions, Action timeout, Max tool steps, Auto-compact, Session budget, Compact threshold, Compact model, Preserve turns |
The model picker offers a curated catalog per provider and Custom for any other model ID. The first-run setup wizard offers the provider, model and key as its AI Copilot step.
The layering matters. Environment variables are the boot baseline; a value saved in the UI is persisted and wins on every later read, hot, with no restart. So an install configured entirely from Helm keeps working, and the moment someone saves a field on the Configuration page, that value is the authority (fields left untouched keep following the environment). Reset to env defaults clears every stored value, keys included. Keys are encrypted at rest and never returned to the browser — the form uses reveal-and-replace, so an empty key field means “unchanged”, not “clear it”.
Settings saved from the UI live in KubeBolt’s BoltDB database, so this needs
authentication enabled (the default). The stored keys are encrypted with a key
derived from the JWT secret: if the secret changes (for example, it was
auto-generated and the API restarted), they can’t be decrypted and KubeBolt
falls back to the environment key. Set a stable KUBEBOLT_JWT_SECRET (or
auth.jwtSecret / auth.existingSecret in Helm).
Administration → AI (Kobi) → Usage shows sessions, tokens, cache hit rate and a cost estimate; Health shows how answers end and the feedback on them.
Verify it worked
-
Restart the API pod after changing env or Helm values, then check the log:
kubectl -n <namespace> logs deployment/kubebolt-api | grep -i "AI copilot"AI copilot enabled provider=... model=...means the environment carries a key (an emptymodelmeans the provider’s default).AI copilot disabled (KUBEBOLT_AI_API_KEY not set)means it doesn’t — that line only reflects the environment, so a key saved in the UI still enables Kobi. -
Ask the API what it resolved, UI-saved settings included. The endpoint needs no token and never returns a key:
curl -s https://kubebolt.example.com/api/v1/copilot/config | jq '{enabled, provider, model}' -
In the UI, the Kobi launcher appears bottom-right and
⌘J(Ctrl+Jon Linux and Windows) toggles the panel. Ask “how many pods are running?”: a tool card means Kobi reached the cluster.
If Kobi answers but says there is no cluster to inspect, the copilot is fine and the cluster is not connected — Kobi’s tools read through the cluster connector. See Troubleshooting.
Turning it off
helm upgrade kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
-n kubebolt --reset-then-reuse-values --set copilot.enabled=false
If a key was saved from the UI, also click Reset to env defaults in
Administration → AI (Kobi) → Configuration — the stored key outranks the
chart. With no key left, the launcher and ⌘J disappear. To keep Kobi but make
it read-only, turn Kobi actions off on that page (or set
KUBEBOLT_AI_ACTIONS_ENABLED=false) instead.