Enabling Kobi

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.

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.

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 \
  --from-literal=api-key=$ANTHROPIC_API_KEY

helm upgrade --install kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  --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: 4096
  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: ""

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.

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.

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. Both are enforced server-side, not only withheld from the model. See Actions & Governance.

Conversation-memory variables (KUBEBOLT_AI_AUTO_COMPACT and friends) are documented in Kobi Copilot.

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.

In the UI

Administration → AI (Kobi) → Configuration (/admin/ai, Admin role) edits the same settings without a redeploy: provider, model, key, fallback, max tool steps, tool-call cards, the two action switches and the action timeout. The first-run setup wizard offers the same form 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.

Verify it worked

Restart the API pod after changing env or Helm values, then check the log:

kubectl logs deployment/kubebolt-api | grep -i "AI copilot"

AI copilot enabled provider=... model=... means the environment carries a key. 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. In the UI, the Kobi launcher appears bottom-right and ⌘J (Ctrl+J on Linux and Windows) toggles the panel.

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 \
  --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, set KUBEBOLT_AI_ACTIONS_ENABLED=false instead.