KubeBolt docs
ENES GitHub

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
  1. The switch is the API key
  2. With Helm
  3. With environment variables
  4. The fallback provider
  5. The escalation model
  6. In the UI
  7. Verify it worked
  8. Turning it off

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.

VariableHelm valueDefaultWhat it does
KUBEBOLT_AI_API_KEYcopilot.existingSecret / copilot.apiKey—Your provider key. Empty disables Kobi.
KUBEBOLT_AI_PROVIDERcopilot.provideranthropicanthropic or openai (openai covers every OpenAI-compatible API)
KUBEBOLT_AI_MODELcopilot.modelclaude-haiku-5-5 (anthropic) · gpt-4o (openai)Model id
KUBEBOLT_AI_BASE_URLcopilot.baseUrlprovider defaultFull endpoint URL, used as-is (e.g. …/v1/chat/completions)
KUBEBOLT_AI_MAX_TOKENScopilot.maxTokensper modelCeiling 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_TTLcopilot.cacheTtl1hAnthropic 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_ROUNDSextraEnv20Tool-calling rounds per answer, clamped to 2–40. On the last one Kobi summarizes what it found instead of failing
KUBEBOLT_AI_SHOW_TOOL_CALLSextraEnvtrueRender each tool call as a card in the panel
KUBEBOLT_AI_ACTIONS_ENABLEDextraEnvtrueMaster switch for the propose_* action tools
KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLEDextraEnvtrueGates delete and scale-to-zero specifically
KUBEBOLT_AI_ACTION_PROGRESS_TIMEOUTextraEnv90sHow 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:

ProviderBase URL
Anthropic (anthropic)built in: https://api.anthropic.com/v1/messages
OpenAIbuilt in: https://api.openai.com/v1/chat/completions
Azure OpenAIhttps://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<version>
xAIhttps://api.x.ai/v1/chat/completions
DeepSeekhttps://api.deepseek.com/v1/chat/completions
Groqhttps://api.groq.com/openai/v1/chat/completions
Mistralhttps://api.mistral.ai/v1/chat/completions
OpenRouterhttps://openrouter.ai/api/v1/chat/completions
Ollamahttp://<host>:11434/v1/chat/completions
vLLMhttp://<host>:8000/v1/chat/completions

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:

CardFields
Primary providerProvider, Model, Escalation model, API key, Base URL
Fallback providerProvider, Model, Fallback API key, Fallback base URL
BehaviorMax 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

  1. 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 empty model means 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.

  2. 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}'
  3. In the UI, the Kobi launcher appears bottom-right and ⌘J (Ctrl+J on 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.