Configuration
Environment variables
Every KUBEBOLT_* variable an operator sets on the API and the agent, grouped by area, with the code default for each.
On this page
This page lists every KUBEBOLT_* variable an operator might set, on the API
and on the agent, grouped by area. Variables that only matter to
KubeBolt Cloud’s multi-tenant build are left out. .env.example at the root of
the repository is the commented reference; deploy/.env.example is its Docker
Compose twin.
Environment is the boot baseline, not the last word. Most of these have a
matching field in the Administration pages. A value saved there is
persisted and wins on every later read, so config-as-code keeps working until
someone edits that setting in the UI — from then on the UI is the authority
for it. Most UI changes apply with no restart; the exceptions are flagged
below. With KUBEBOLT_AUTH_ENABLED=false there are no Administration pages
and the environment is the only layer.
Defaults below are what the code falls back to when the variable is unset. Where the Helm chart or the Docker Compose file sets a different value, the row says so. To see what the running API actually received, open Administration → System → Boot snapshot.
Flags and precedence
The API binary takes a few flags. They win over everything else; then come the
process environment, then a .env file in the working directory (it only fills
gaps), then the code defaults.
| Flag | Default | What it does |
|---|---|---|
--port | 8080 | HTTP port: REST, WebSocket and, in the single binary, the UI |
--host | 0.0.0.0 | Bind address. The agent gRPC listener uses it too, on port 9090, unless KUBEBOLT_AGENT_GRPC_ADDR says otherwise |
--kubeconfig | $KUBECONFIG, else ~/.kube/config | Kubeconfig to load. With no file there and a ServiceAccount mounted, the API uses the in-cluster configuration |
--metric-interval | 30 | Seconds between Metrics Server polls |
--insight-interval | 60 | Seconds between insight evaluations |
--reset-admin-password | — | Sets the admin password, then exits |
Core
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_DATA_DIR | ./data | Where the embedded BoltDB lives: users, tokens, settings, agent registry, insight history, Kobi’s conversations. Mount a persistent volume here. Only opened with authentication on. Cannot be set from the UI |
KUBEBOLT_CORS_ORIGINS | http://localhost:3000,http://localhost:5173 | Comma-separated allowed origins. Required when the UI is served from a different origin than the API. Wildcards work |
KUBEBOLT_DISPLAY_NAME | KubeBolt | Label in the top bar and browser title, to tell installs apart |
KUBEBOLT_LOG_LEVEL | info | debug, info, warn, error |
KUBEBOLT_LOG_FORMAT | text | text or json |
KUBEBOLT_LOG_DIR | — | When set, logs are also appended to kubebolt.log in that directory |
KUBEBOLT_UPDATE_CHECK_ENABLED | true | Periodic check of the GitHub releases API. Set false when air-gapped |
KUBEBOLT_CACHE_SYNC_TIMEOUT_SECONDS | 45 | How long a cold cluster connect’s informer cache sync may receive nothing before it fails. A sync still receiving pages carries on, up to 10 minutes. Floored at 5 |
KUBEBOLT_DEFAULT_REFRESH_INTERVAL_SECONDS | 30 | Fallback UI refresh cadence. One of 5, 10, 15, 30, 60, 120 |
KUBEBOLT_PROD_NAMESPACE_PATTERN | namespaces named prod, production or prd, alone or with a - or _ suffix | Regular expression that marks a namespace as production: revealing a Secret there takes the admin role, elsewhere editor is enough |
Metrics store
Where history lives. Details, and the chart values for the bundled VictoriaMetrics, in Metrics.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_METRICS_STORAGE_URL | http://localhost:8428 | VictoriaMetrics base URL. Unset and with nothing answering there at boot, the API keeps no history and says so in its log. The Helm chart and Docker Compose always set it |
KUBEBOLT_METRICS_STORAGE_TOKEN | — | Bearer token for a store that asks for one. Wins over basic auth |
KUBEBOLT_METRICS_STORAGE_USERNAME · _PASSWORD | — | Basic auth for the store. Credentials written in the URL also work |
KUBEBOLT_METRICS_RETENTION | 30d | Docker Compose only: the bundled VictoriaMetrics’ --retentionPeriod. With Helm it is metrics.storage.embedded.retention |
None of these can be changed from the UI.
Authentication
Full context in Authentication.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_AUTH_ENABLED | true | Set false only when access is already restricted at the network layer. With it off there is no embedded store: no Administration pages, saved settings, insight history, security findings, Kobi conversations or cloud connectors |
KUBEBOLT_ADMIN_PASSWORD | auto-generated | Seeds the admin password on first boot. Ignored once the admin exists |
KUBEBOLT_RESET_ADMIN_PASSWORD | — | Resets the admin password on the next boot, then continues booting. Read before .env, so it has to be a real environment variable. Clear it afterwards |
KUBEBOLT_JWT_SECRET | auto-generated, persisted | Signing key. An operator-supplied value under 32 bytes fails the boot on purpose |
KUBEBOLT_JWT_EXPIRY | 15m | Access-token lifetime |
KUBEBOLT_JWT_REFRESH_EXPIRY | 168h | Refresh-token lifetime (7 days) |
Both JWT lifetimes are editable in Administration → Access → Authentication but need a restart, because the JWT service is wired at boot. The UI flags that.
AI and Kobi
The full set, and the Helm equivalents, are in Enabling Kobi.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_AI_API_KEY | — | This is the switch. Kobi is off when neither this nor a key saved in Administration → AI (Kobi) → Configuration is set |
KUBEBOLT_AI_PROVIDER | anthropic | anthropic or openai — the only two values; every OpenAI-compatible API uses openai |
KUBEBOLT_AI_MODEL | claude-haiku-5-5 · gpt-4o | Provider default when unset |
KUBEBOLT_AI_BASE_URL | provider default | Full endpoint URL, used verbatim — for OpenAI-compatible APIs it must end in /chat/completions |
KUBEBOLT_AI_MAX_TOKENS | per model | Ceiling per response: 16384 where reasoning counts against it, 4096 elsewhere |
KUBEBOLT_AI_MAX_ROUNDS | 20 | Tool-calling rounds per answer. Clamped to 2–40 |
KUBEBOLT_AI_CACHE_TTL | 1h | Anthropic only: how long the cached prompt prefix lives. 5m goes back to the API’s short cache, cheaper when questions are one-off |
KUBEBOLT_AI_FALLBACK_API_KEY | — | Setting this arms the fallback provider. _PROVIDER defaults to the primary’s; _MODEL and _BASE_URL are optional |
KUBEBOLT_AI_ESCALATION_MODEL | — | Setting this arms the escalation model. _PROVIDER defaults to the primary’s, and with the same provider _API_KEY and _BASE_URL do too |
KUBEBOLT_AI_ACTIONS_ENABLED | true | Master switch for the propose_* action tools |
KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLED | true | Gates delete and scale-to-zero |
KUBEBOLT_AI_ACTION_PROGRESS_TIMEOUT | 90s | How long the UI polls an executed action for convergence. Floored at 10s |
KUBEBOLT_AI_AUTO_COMPACT | true | Fold old turns into a summary as the context fills |
KUBEBOLT_AI_AUTO_COMPACT_THRESHOLD | 0.80 | Fraction of the budget at which compaction fires. Must be between 0 and 1 |
KUBEBOLT_AI_SESSION_BUDGET_TOKENS | model context window | The budget compaction measures against |
KUBEBOLT_AI_COMPACT_MODEL | claude-haiku-5-5 · gpt-4o-mini | Model that writes the summary. Set it for any non-OpenAI endpoint |
KUBEBOLT_AI_COMPACT_PRESERVE_TURNS | 3 | Turns kept intact after a fold |
KUBEBOLT_AI_SHOW_TOOL_CALLS | true | Render each tool call as a card in the panel |
Cloud connectors
See Cloud connectors. They need authentication on: without the embedded store there is nowhere to keep a connector.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_MCP_CONNECTORS | on | false removes the Connectors tab and the cloud tools |
KUBEBOLT_MCP_AWS_PRINCIPAL_ARN | — | The AWS identity KubeBolt runs as, printed in the trust policy of the setup guide |
KUBEBOLT_MCP_AZMCP_URL | http://127.0.0.1:5001/ | Where the Azure MCP Server sidecar listens. Loopback only |
KUBEBOLT_MCP_TOOL_TIMEOUT | 30s | Per-call timeout, as a Go duration or seconds. AWS’s first call in a session takes 9–12 s |
Notifications
See Notifications, including which changes made in the UI wait for a restart.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_NOTIFICATIONS_ENABLED | true | Global kill switch. false silences every channel without unconfiguring it |
KUBEBOLT_NOTIFICATIONS_MIN_SEVERITY | warning | critical, warning, info. An invalid value falls back to warning |
KUBEBOLT_NOTIFICATIONS_COOLDOWN | 1h | Dedup window for the same insight on the same cluster |
KUBEBOLT_NOTIFICATIONS_INCLUDE_RESOLVED | false | Also notify when an insight resolves |
KUBEBOLT_NOTIFICATIONS_BASE_URL | — | Public URL used to build links inside messages |
KUBEBOLT_SLACK_WEBHOOK_URL · KUBEBOLT_DISCORD_WEBHOOK_URL | — | Configuring a URL enables that channel |
KUBEBOLT_SLACK_ENABLED · KUBEBOLT_DISCORD_ENABLED · KUBEBOLT_EMAIL_ENABLED | true | Pause one channel without clearing its destination |
KUBEBOLT_SMTP_HOST · _USERNAME · _PASSWORD · _FROM · _TO | — | Email needs host, from, and at least one recipient to count as configured. _TO is comma-separated |
KUBEBOLT_SMTP_PORT | 587 | STARTTLS when the server offers it; 465 uses implicit TLS |
KUBEBOLT_SMTP_DIGEST_MODE | instant | instant, hourly, daily |
KUBEBOLT_NOTIFICATIONS_BURST_THRESHOLD | 5 | Insights one cluster opens within the window that turn into one summary. 2–1000 |
KUBEBOLT_NOTIFICATIONS_BURST_WINDOW | 60s | How far back that count looks. 10 s–1 h |
KUBEBOLT_NOTIFICATIONS_BURST_QUIET | 30s | The summary goes out once the cluster has been quiet this long. 5 s–10 min, never longer than the maximum wait |
KUBEBOLT_NOTIFICATIONS_BURST_MAX_WAIT | 5m | A burst that does not settle gets a partial still going summary this often. 30 s–1 h |
KUBEBOLT_NOTIFICATIONS_DIGEST_LIST_LIMIT | 20 | An hourly or daily digest with more insights than this is sent as a summary. 1–500 |
Agent ingest
The channel between the agent and the backend. Defaults are permissive so a fresh install boots and can then be locked down from Administration → Agents & Ingest → Configuration.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_AGENT_GRPC_ADDR | <--host>:9090 | Where the gRPC listener binds |
KUBEBOLT_AGENT_AUTH_MODE | disabled | disabled, permissive, enforced. Restart required |
KUBEBOLT_AGENT_TOKEN_AUDIENCE | kubebolt-backend | Expected audience on agent tokens. Restart required |
KUBEBOLT_AGENT_TLS_CERT_FILE · _TLS_KEY_FILE | — | Server certificate and key for the gRPC channel. Both or neither; unset means plaintext |
KUBEBOLT_AGENT_TLS_CLIENT_CA | — | CA bundle that verifies agent client certificates when they present one |
KUBEBOLT_AGENT_REQUIRE_MTLS | false | Reject agents without a verified client certificate. Needs _TLS_CLIENT_CA. Restart required |
KUBEBOLT_AGENT_INGEST_URL | — | External host:port remote agents dial. Setting it marks the install as hosted and changes the wizard’s defaults |
KUBEBOLT_AGENT_AUTOREGISTER_CLUSTERS | false (the Helm chart sets true) | Add a cluster to the switcher when its agent connects. Off, the agent ships metrics but its cluster does not appear in the switcher |
KUBEBOLT_AGENT_REGISTRY_PRUNE_HORIZON | 24h | When a stale agent record is pruned |
KUBEBOLT_AGENT_RATE_LIMIT_ENABLED | false | Fleet-wide rate limit on the ingest channel |
KUBEBOLT_AGENT_RATE_LIMIT_RPS · _BURST | 1000 · 2000 | Its rate and burst |
KUBEBOLT_AGENT_TUNNEL_IDLE_TIMEOUT | 5m | Idle tunnels (exec, port-forward) close after this. 0 disables the watchdog |
KUBEBOLT_AGENT_PROXY_CONNECT_TIMEOUT | 60s (25s before 2.6.7) | How long a cold connect through an agent may receive nothing before it fails. A connect still receiving pages carries on, up to 10 minutes |
KUBEBOLT_AGENT_PROXY_STUCK_TIMEOUT | 45s | Stuck-agent watchdog. 0 disables it |
KUBEBOLT_AGENT_PROXY_REQUEST_TIMEOUT | 30s | Per-request deadline through the tunnel |
KUBEBOLT_AGENT_MAX_MSG_BYTES | 67108864 (64 MiB) | Largest gRPC message on the channel. Large clusters send API responses over 4 MiB. Keep it equal to the agent’s |
The three proxy timeouts accept 5–600 s; a value outside that range keeps the default. Since 2.6.7 the connect and stuck timeouts are never applied below the request timeout + 5 s (35 s with the default 30 s): a lower value is raised, the API logs it, and Settings › Agents & Ingest shows the value that runs. The TLS files are read at boot only.
KUBEBOLT_AGENT_PROXY_CONNECT_TIMEOUT measures silence since 2.6.5: a
large cluster that is still receiving pages is no longer cut by it. Raise it
only if a cluster reports “Cluster unreachable” while it is still syncing —
see Troubleshooting. It is a blunt instrument: it
also loosens the protection that exists for genuinely wedged agents.
Metrics ingest
The Prometheus remote_write receiver. See
Metrics.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_REMOTE_WRITE_ENABLED | false | Accept Prometheus remote_write at /api/v1/prom/write. Off, the route answers 404 |
KUBEBOLT_REMOTE_WRITE_AUTH_MODE | disabled | disabled, permissive, enforced |
KUBEBOLT_PROM_WRITE_DEFAULT_SAMPLES_PER_SEC | 10000 | Per-tenant sample rate |
KUBEBOLT_PROM_WRITE_DEFAULT_BURST_SAMPLES | 100000 | Its burst |
KUBEBOLT_PROM_WRITE_DEFAULT_MAX_ACTIVE_SERIES | 1000000 | Per-tenant active-series ceiling |
KUBEBOLT_PROM_WRITE_DEFAULT_MAX_ACTIVE_SERIES_GLOBAL | 0 (off) | Install-wide ceiling |
KUBEBOLT_PROM_WRITE_ALLOW_CUSTOM_SERIES | false (Docker Compose sets true) | false drops every series outside KubeBolt’s own metric families; true keeps your application metrics too |
KUBEBOLT_PROM_WRITE_NAME_FILTER_ENABLED | true | false skips that classification entirely and forwards everything |
Retention
One hourly pass, per organization; the _HORIZON values are re-read from the
environment on every pass. Durations are Go durations. Active insights never expire, and neither do firing
episodes. Metric history has its own retention, set on the
metrics store.
| Variable | Default | What it bounds |
|---|---|---|
KUBEBOLT_INSIGHTS_RETENTION_HORIZON | 168h (7 days) | Resolved insight records (one per fingerprint). Episodes follow the findings horizon below |
KUBEBOLT_INSIGHT_EXPIRE_TTL | 15m | A firing episode with no signal for longer flips to expired instead of staying active forever after an agent leaves |
KUBEBOLT_FINDINGS_RETENTION_HORIZON | 720h (30 days) | Resolved security findings (active ones never expire), runtime events, and insight episodes |
KUBEBOLT_AUDIT_RETENTION_HORIZON | 2160h (90 days) | The mutation and access audit trail |
KUBEBOLT_COPILOT_CONVERSATION_RETENTION_HORIZON | 2160h (90 days) | Kobi transcripts — the highest-PII store in the product |
KUBEBOLT_COPILOT_CONVERSATION_MAX_PER_USER | 200 | Conversations kept per user |
On Cloud these are not yours to set: retention is a plan dimension, listed in Security and compliance.
Self-monitoring
The API can push a second copy of its own health series (HTTP, background jobs, calls to VictoriaMetrics, WebSocket, agent channels, process) to a Prometheus outside the install, so an outage of the API or of its store is still visible somewhere. Only platform series cross: no cluster or tenant identifiers, nothing from Kobi. Off unless the URL is set.
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_EXTERNAL_METRICS_URL | — | remote_write endpoint, for example Grafana Cloud’s |
KUBEBOLT_EXTERNAL_METRICS_USER · _TOKEN | — | Basic-auth user and password for it |
KUBEBOLT_EXTERNAL_METRICS_LABELS | — | Extra labels on every series, as key=value,key=value, to tell installs apart |
KUBEBOLT_EXTERNAL_METRICS_INTERVAL | 60s | Push interval. Values under 15s are ignored |
A Prometheus of your own can also scrape the API’s /metrics endpoint, and
the chart’s metrics.alertRules.enabled ships alert rules for it as a
PrometheusRule.
Agent
The agent reads its own variables. The agent chart
writes them from its values, so you set the value; where there is none, use
the agent chart’s extraEnv.
| Variable | Chart value | Default | What it does |
|---|---|---|---|
KUBEBOLT_BACKEND_URL | backendUrl | localhost:9090 (the chart requires it) | gRPC dial target, host:port, no scheme |
KUBEBOLT_AGENT_MODE | set per workload | unset runs everything | daemonset on the DaemonSet pods, promread on the read-your-Prometheus Deployment |
KUBEBOLT_AGENT_CLUSTER_NAME | cluster.name | — | The name the cluster registers with |
KUBEBOLT_AGENT_CLUSTER_ID | cluster.id | the kube-system namespace UID | Override only to keep an ID a legacy install used |
KUBEBOLT_AGENT_LOG_LEVEL | logLevel | info | debug, info, warn, error |
KUBEBOLT_AGENT_PROXY_ENABLED | derived from rbac.mode | false | Carries the API tunnel. The chart turns it on for reader and operator |
KUBEBOLT_AGENT_AUTH_MODE · _TOKEN_FILE | auth.mode, auth.ingestToken.*, auth.tokenReview.* | no credentials | tokenreview or ingest-token, and the mounted token |
KUBEBOLT_AGENT_TLS_ENABLED · _TLS_CA_FILE · _TLS_CERT_FILE · _TLS_KEY_FILE · _TLS_SERVER_NAME | tls.* | plaintext | TLS to the backend. A client certificate adds mTLS |
KUBEBOLT_AGENT_MAX_MSG_BYTES | extraEnv | 67108864 (64 MiB) | Largest gRPC message. Keep it equal to the API’s |
KUBEBOLT_HUBBLE_ENABLED | hubble.enabled | true in the binary, false in the chart | Hubble flow collector |
KUBEBOLT_HUBBLE_RELAY_ADDR | hubble.relay.address | hubble-relay.kube-system.svc.cluster.local:80 | Hubble relay to read flows from |
KUBEBOLT_HUBBLE_RELAY_CA_FILE · _CERT_FILE · _KEY_FILE · _SERVER_NAME | hubble.relay.tls.* | plaintext | TLS or mTLS to the relay |
KUBEBOLT_AGENT_DROP_NET_INTERFACES | collectors.dropNetworkInterfaces | none in the binary; the chart drops tunnel devices, per-pod veth peers and lo | Interfaces left out of container_network_*. A trailing * prefix-matches |
KUBEBOLT_AGENT_EXPORTERS | collectors.exporters, opencost.* | — | Extra Prometheus exporters, as name=url pairs. One pod in the cluster scrapes each |
KUBEBOLT_AGENT_DEFER_NODE_NETWORK · _DEFER_NODE_STRESS | agent.deferNodeNetwork, agent.deferNodeStress | false | Leave node network, or load and PSI, to a node-exporter you already scrape. The chart sets both when its node-exporter scrape is on |
KUBEBOLT_AGENT_PROMREAD_* | agent.promRead.* | off | Read-from-Prometheus mode: URL, auth, poll interval, step, lookback, matchers, cost |
KUBEBOLT_TENANT_ID | tenant.id | — | Leave empty: the backend takes the tenant from the ingest token |
GOMEMLIMIT | gomemlimit | 90% of each container’s memory limit | Go memory target |
KUBEBOLT_AGENT_MEMORY_LIMIT_BYTES | set from resources.limits.memory | — | The container’s memory limit. One body the agent relays is capped at a quarter of it, never above 63 MiB (details) |
Development and escape hatches
| Variable | Default | What it does |
|---|---|---|
KUBEBOLT_WATCHLIST_CLIENT | false | true restores client-go’s streaming initial list. Only for installs that never reach a cluster through an agent: over the tunnel it silently truncates caches |
KUBEBOLT_AI_DEBUG | — | Legacy. 1 forces KUBEBOLT_LOG_LEVEL=debug |
KUBEBOLT_AGENT_PPROF_ADDR | — | Agent only. Serves /debug/pprof on that address; use 127.0.0.1:6060 with kubectl port-forward |
Setting them
With Helm, these chart values write the variables for you:
| Chart value | Variables |
|---|---|
auth.* | KUBEBOLT_AUTH_ENABLED, KUBEBOLT_ADMIN_PASSWORD, KUBEBOLT_JWT_SECRET, KUBEBOLT_RESET_ADMIN_PASSWORD, and KUBEBOLT_DATA_DIR on the chart’s volume |
copilot.*, with copilot.enabled=true | KUBEBOLT_AI_PROVIDER, _MODEL, _BASE_URL, _MAX_TOKENS, _CACHE_TTL, _API_KEY, _FALLBACK_*, _ESCALATION_MODEL |
mcpConnectors.* | KUBEBOLT_MCP_CONNECTORS, KUBEBOLT_MCP_AWS_PRINCIPAL_ARN |
agentIngest.* | KUBEBOLT_AGENT_GRPC_ADDR, _AUTH_MODE, _TOKEN_AUDIENCE, _INGEST_URL, _AUTOREGISTER_CLUSTERS, _RATE_LIMIT_*, _TLS_*, _REQUIRE_MTLS |
metrics.storage.* | KUBEBOLT_METRICS_STORAGE_URL and its credentials |
metrics.remoteWrite.* | KUBEBOLT_REMOTE_WRITE_ENABLED, KUBEBOLT_REMOTE_WRITE_AUTH_MODE |
For anything without one, use the chart’s escape hatch rather than waiting for a template change:
extraEnv:
- name: KUBEBOLT_FINDINGS_RETENTION_HORIZON
value: "2160h"
- name: KUBEBOLT_AGENT_PROXY_CONNECT_TIMEOUT
value: "90s"
With Docker Compose, copy deploy/.env.example to deploy/.env and edit it.
Compose passes the container only the variables listed under environment: in
deploy/docker-compose.yml. Logging, the notification channels and the agent
auth mode are not among them: add a line there, or, for the last two, set them
in the Administration pages.
Running the binary, put them in a .env file in the directory you start it
from. System environment variables take precedence over the file — it only
fills gaps.