KubeBolt docs
ENES GitHub

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
  1. Flags and precedence
  2. Core
  3. Metrics store
  4. Authentication
  5. AI and Kobi
  6. Cloud connectors
  7. Notifications
  8. Agent ingest
  9. Metrics ingest
  10. Retention
  11. Self-monitoring
  12. Agent
  13. Development and escape hatches
  14. Setting them

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.

FlagDefaultWhat it does
--port8080HTTP port: REST, WebSocket and, in the single binary, the UI
--host0.0.0.0Bind address. The agent gRPC listener uses it too, on port 9090, unless KUBEBOLT_AGENT_GRPC_ADDR says otherwise
--kubeconfig$KUBECONFIG, else ~/.kube/configKubeconfig to load. With no file there and a ServiceAccount mounted, the API uses the in-cluster configuration
--metric-interval30Seconds between Metrics Server polls
--insight-interval60Seconds between insight evaluations
--reset-admin-password—Sets the admin password, then exits

Core

VariableDefaultWhat it does
KUBEBOLT_DATA_DIR./dataWhere 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_ORIGINShttp://localhost:3000,http://localhost:5173Comma-separated allowed origins. Required when the UI is served from a different origin than the API. Wildcards work
KUBEBOLT_DISPLAY_NAMEKubeBoltLabel in the top bar and browser title, to tell installs apart
KUBEBOLT_LOG_LEVELinfodebug, info, warn, error
KUBEBOLT_LOG_FORMATtexttext or json
KUBEBOLT_LOG_DIR—When set, logs are also appended to kubebolt.log in that directory
KUBEBOLT_UPDATE_CHECK_ENABLEDtruePeriodic check of the GitHub releases API. Set false when air-gapped
KUBEBOLT_CACHE_SYNC_TIMEOUT_SECONDS45How 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_SECONDS30Fallback UI refresh cadence. One of 5, 10, 15, 30, 60, 120
KUBEBOLT_PROD_NAMESPACE_PATTERNnamespaces named prod, production or prd, alone or with a - or _ suffixRegular 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.

VariableDefaultWhat it does
KUBEBOLT_METRICS_STORAGE_URLhttp://localhost:8428VictoriaMetrics 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_RETENTION30dDocker 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.

VariableDefaultWhat it does
KUBEBOLT_AUTH_ENABLEDtrueSet 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_PASSWORDauto-generatedSeeds 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_SECRETauto-generated, persistedSigning key. An operator-supplied value under 32 bytes fails the boot on purpose
KUBEBOLT_JWT_EXPIRY15mAccess-token lifetime
KUBEBOLT_JWT_REFRESH_EXPIRY168hRefresh-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.

VariableDefaultWhat 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_PROVIDERanthropicanthropic or openai — the only two values; every OpenAI-compatible API uses openai
KUBEBOLT_AI_MODELclaude-haiku-5-5 · gpt-4oProvider default when unset
KUBEBOLT_AI_BASE_URLprovider defaultFull endpoint URL, used verbatim — for OpenAI-compatible APIs it must end in /chat/completions
KUBEBOLT_AI_MAX_TOKENSper modelCeiling per response: 16384 where reasoning counts against it, 4096 elsewhere
KUBEBOLT_AI_MAX_ROUNDS20Tool-calling rounds per answer. Clamped to 2–40
KUBEBOLT_AI_CACHE_TTL1hAnthropic 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_ENABLEDtrueMaster switch for the propose_* action tools
KUBEBOLT_AI_DESTRUCTIVE_ACTIONS_ENABLEDtrueGates delete and scale-to-zero
KUBEBOLT_AI_ACTION_PROGRESS_TIMEOUT90sHow long the UI polls an executed action for convergence. Floored at 10s
KUBEBOLT_AI_AUTO_COMPACTtrueFold old turns into a summary as the context fills
KUBEBOLT_AI_AUTO_COMPACT_THRESHOLD0.80Fraction of the budget at which compaction fires. Must be between 0 and 1
KUBEBOLT_AI_SESSION_BUDGET_TOKENSmodel context windowThe budget compaction measures against
KUBEBOLT_AI_COMPACT_MODELclaude-haiku-5-5 · gpt-4o-miniModel that writes the summary. Set it for any non-OpenAI endpoint
KUBEBOLT_AI_COMPACT_PRESERVE_TURNS3Turns kept intact after a fold
KUBEBOLT_AI_SHOW_TOOL_CALLStrueRender 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.

VariableDefaultWhat it does
KUBEBOLT_MCP_CONNECTORSonfalse 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_URLhttp://127.0.0.1:5001/Where the Azure MCP Server sidecar listens. Loopback only
KUBEBOLT_MCP_TOOL_TIMEOUT30sPer-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.

VariableDefaultWhat it does
KUBEBOLT_NOTIFICATIONS_ENABLEDtrueGlobal kill switch. false silences every channel without unconfiguring it
KUBEBOLT_NOTIFICATIONS_MIN_SEVERITYwarningcritical, warning, info. An invalid value falls back to warning
KUBEBOLT_NOTIFICATIONS_COOLDOWN1hDedup window for the same insight on the same cluster
KUBEBOLT_NOTIFICATIONS_INCLUDE_RESOLVEDfalseAlso 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_ENABLEDtruePause 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_PORT587STARTTLS when the server offers it; 465 uses implicit TLS
KUBEBOLT_SMTP_DIGEST_MODEinstantinstant, hourly, daily
KUBEBOLT_NOTIFICATIONS_BURST_THRESHOLD5Insights one cluster opens within the window that turn into one summary. 2–1000
KUBEBOLT_NOTIFICATIONS_BURST_WINDOW60sHow far back that count looks. 10 s–1 h
KUBEBOLT_NOTIFICATIONS_BURST_QUIET30sThe 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_WAIT5mA burst that does not settle gets a partial still going summary this often. 30 s–1 h
KUBEBOLT_NOTIFICATIONS_DIGEST_LIST_LIMIT20An 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.

VariableDefaultWhat it does
KUBEBOLT_AGENT_GRPC_ADDR<--host>:9090Where the gRPC listener binds
KUBEBOLT_AGENT_AUTH_MODEdisableddisabled, permissive, enforced. Restart required
KUBEBOLT_AGENT_TOKEN_AUDIENCEkubebolt-backendExpected 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_MTLSfalseReject 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_CLUSTERSfalse (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_HORIZON24hWhen a stale agent record is pruned
KUBEBOLT_AGENT_RATE_LIMIT_ENABLEDfalseFleet-wide rate limit on the ingest channel
KUBEBOLT_AGENT_RATE_LIMIT_RPS · _BURST1000 · 2000Its rate and burst
KUBEBOLT_AGENT_TUNNEL_IDLE_TIMEOUT5mIdle tunnels (exec, port-forward) close after this. 0 disables the watchdog
KUBEBOLT_AGENT_PROXY_CONNECT_TIMEOUT60s (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_TIMEOUT45sStuck-agent watchdog. 0 disables it
KUBEBOLT_AGENT_PROXY_REQUEST_TIMEOUT30sPer-request deadline through the tunnel
KUBEBOLT_AGENT_MAX_MSG_BYTES67108864 (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.

VariableDefaultWhat it does
KUBEBOLT_REMOTE_WRITE_ENABLEDfalseAccept Prometheus remote_write at /api/v1/prom/write. Off, the route answers 404
KUBEBOLT_REMOTE_WRITE_AUTH_MODEdisableddisabled, permissive, enforced
KUBEBOLT_PROM_WRITE_DEFAULT_SAMPLES_PER_SEC10000Per-tenant sample rate
KUBEBOLT_PROM_WRITE_DEFAULT_BURST_SAMPLES100000Its burst
KUBEBOLT_PROM_WRITE_DEFAULT_MAX_ACTIVE_SERIES1000000Per-tenant active-series ceiling
KUBEBOLT_PROM_WRITE_DEFAULT_MAX_ACTIVE_SERIES_GLOBAL0 (off)Install-wide ceiling
KUBEBOLT_PROM_WRITE_ALLOW_CUSTOM_SERIESfalse (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_ENABLEDtruefalse 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.

VariableDefaultWhat it bounds
KUBEBOLT_INSIGHTS_RETENTION_HORIZON168h (7 days)Resolved insight records (one per fingerprint). Episodes follow the findings horizon below
KUBEBOLT_INSIGHT_EXPIRE_TTL15mA firing episode with no signal for longer flips to expired instead of staying active forever after an agent leaves
KUBEBOLT_FINDINGS_RETENTION_HORIZON720h (30 days)Resolved security findings (active ones never expire), runtime events, and insight episodes
KUBEBOLT_AUDIT_RETENTION_HORIZON2160h (90 days)The mutation and access audit trail
KUBEBOLT_COPILOT_CONVERSATION_RETENTION_HORIZON2160h (90 days)Kobi transcripts — the highest-PII store in the product
KUBEBOLT_COPILOT_CONVERSATION_MAX_PER_USER200Conversations 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.

VariableDefaultWhat 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_INTERVAL60sPush 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.

VariableChart valueDefaultWhat it does
KUBEBOLT_BACKEND_URLbackendUrllocalhost:9090 (the chart requires it)gRPC dial target, host:port, no scheme
KUBEBOLT_AGENT_MODEset per workloadunset runs everythingdaemonset on the DaemonSet pods, promread on the read-your-Prometheus Deployment
KUBEBOLT_AGENT_CLUSTER_NAMEcluster.name—The name the cluster registers with
KUBEBOLT_AGENT_CLUSTER_IDcluster.idthe kube-system namespace UIDOverride only to keep an ID a legacy install used
KUBEBOLT_AGENT_LOG_LEVELlogLevelinfodebug, info, warn, error
KUBEBOLT_AGENT_PROXY_ENABLEDderived from rbac.modefalseCarries the API tunnel. The chart turns it on for reader and operator
KUBEBOLT_AGENT_AUTH_MODE · _TOKEN_FILEauth.mode, auth.ingestToken.*, auth.tokenReview.*no credentialstokenreview or ingest-token, and the mounted token
KUBEBOLT_AGENT_TLS_ENABLED · _TLS_CA_FILE · _TLS_CERT_FILE · _TLS_KEY_FILE · _TLS_SERVER_NAMEtls.*plaintextTLS to the backend. A client certificate adds mTLS
KUBEBOLT_AGENT_MAX_MSG_BYTESextraEnv67108864 (64 MiB)Largest gRPC message. Keep it equal to the API’s
KUBEBOLT_HUBBLE_ENABLEDhubble.enabledtrue in the binary, false in the chartHubble flow collector
KUBEBOLT_HUBBLE_RELAY_ADDRhubble.relay.addresshubble-relay.kube-system.svc.cluster.local:80Hubble relay to read flows from
KUBEBOLT_HUBBLE_RELAY_CA_FILE · _CERT_FILE · _KEY_FILE · _SERVER_NAMEhubble.relay.tls.*plaintextTLS or mTLS to the relay
KUBEBOLT_AGENT_DROP_NET_INTERFACEScollectors.dropNetworkInterfacesnone in the binary; the chart drops tunnel devices, per-pod veth peers and loInterfaces left out of container_network_*. A trailing * prefix-matches
KUBEBOLT_AGENT_EXPORTERScollectors.exporters, opencost.*—Extra Prometheus exporters, as name=url pairs. One pod in the cluster scrapes each
KUBEBOLT_AGENT_DEFER_NODE_NETWORK · _DEFER_NODE_STRESSagent.deferNodeNetwork, agent.deferNodeStressfalseLeave 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.*offRead-from-Prometheus mode: URL, auth, poll interval, step, lookback, matchers, cost
KUBEBOLT_TENANT_IDtenant.id—Leave empty: the backend takes the tenant from the ingest token
GOMEMLIMITgomemlimit90% of each container’s memory limitGo memory target
KUBEBOLT_AGENT_MEMORY_LIMIT_BYTESset 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

VariableDefaultWhat it does
KUBEBOLT_WATCHLIST_CLIENTfalsetrue 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 valueVariables
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=trueKUBEBOLT_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.