Getting Started
Installation Methods
Every way to run KubeBolt yourself — the Helm chart (with Ingress or Gateway API), Docker Compose, the single binary, Homebrew, the single container and the krew plugin.
On this page
Helm Chart (recommended for Kubernetes)
Production deployment inside your cluster. OCI-based chart on GitHub Container Registry. Also listed on Artifact Hub.
helm install kubebolt oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace
kubectl -n kubebolt port-forward svc/kubebolt 3000:80
Or, instead, with an Ingress and your own admin password (the quotes keep zsh from expanding the brackets):
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace \
--set auth.adminPassword=YourSecurePassword \
--set ingress.enabled=true \
--set ingress.className=nginx \
--set 'ingress.hosts[0].host=kubebolt.example.com' \
--set 'ingress.hosts[0].paths[0].path=/' \
--set 'ingress.hosts[0].paths[0].pathType=Prefix'
Add --version 2.7.0 to pin a release instead of taking the latest.
The chart deploys the API, the web UI and a single-node VictoriaMetrics for
history (10 GiB PVC, 30-day retention; a second 1 GiB PVC holds KubeBolt’s own
data — both on the cluster’s default StorageClass), plus a ServiceAccount and a
ClusterRole. The ClusterRole grants read access to every resource type
KubeBolt shows and the write verbs its actions need (exec, port-forward,
evict, scale, restart, edit, create, delete) — set rbac.create=false and
bind your own role if you want a narrower one. KubeBolt probes what its
credentials may do and hides the rest. Configurable values include image
tags, resources, Ingress, auth, metrics storage and RBAC; the full list is in
the chart README.
The first login, the generated admin password and the Setup Wizard are in
Quick Start.
The Ingress carries the UI and the API only. Agents in other clusters dial the gRPC agent port, which it does not route — see Exposing the agent port.
Gateway API
Where ingress-nginx isn’t an option, the chart can expose KubeBolt through
the Gateway API instead (use one or the other, not both). It creates a
Gateway with two HTTPS listeners: one for the UI and API, and one for the
agent gRPC channel, TLS terminated at the gateway. It needs a Gateway API
controller and its CRDs; the defaults target Envoy Gateway (GatewayClass eg).
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace \
--set gatewayAPI.enabled=true \
--set gatewayAPI.api.host=kubebolt.example.com \
--set gatewayAPI.agent.host=agent.kubebolt.example.com \
--set gatewayAPI.certManager.clusterIssuer=letsencrypt-prod \
--set web.enabled=true
web.enabled=trueis required for a self-contained install: without it the route goes straight to the API Service and the UI is not served. It is not listed invalues.yaml.- Without
certManager.clusterIssuer, provide the TLS Secrets yourself (gatewayAPI.api.tlsSecretName,gatewayAPI.agent.tlsSecretName). - Keep
gatewayAPI.forceHTTP1=true(the default) on Envoy Gateway: its HTTP/2 default breaks the WebSocket upgrade (live updates, pod terminal). Set it tofalsewith another controller. - Remote agents then dial
agent.kubebolt.example.com:443withtls.enabled=true. If a CDN proxies your DNS, keep that hostname DNS-only.
The agent chart
Historical metrics, network flows and cost come from the optional agent, shipped as its own OCI chart with an independent release cadence:
helm install kubebolt-agent \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
--namespace kubebolt-system --create-namespace \
--set backendUrl=kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090
That backendUrl is the in-cluster Service of a release named kubebolt in
the kubebolt namespace (<release>-agent-ingest.<namespace>). Remote
clusters dial a public address instead; see Connecting clusters.
In practice you rarely write this command by hand — the Add cluster wizard generates it with the right values for your setup (Prometheus mode, OpenCost, mTLS).
Upgrading: the backend first, then the agent in every cluster that runs
one, each with -n <namespace> --reset-then-reuse-values and never
--reuse-values, which keeps the old chart’s pinned images. Step by step, in
Compatibility → Upgrading.
Docker Compose
Full stack with separate API, web and VictoriaMetrics containers. Compose
builds the API and web images from the checkout, so the first up takes a few
minutes.
deploy/docker-compose.yml and deploy/docker-kubeconfig.sh are files in the
git repository, not published artifacts, so Compose starts with a clone:
git clone https://github.com/clm-cloud-solutions/kubebolt.git
cd kubebolt
# The compose file mounts /tmp/docker-kubeconfig, so every install runs the
# helper first. On remote clusters the rewrite is a no-op; it just copies.
./deploy/docker-kubeconfig.sh
cd deploy && docker compose up -d
Frontend at http://localhost:3000. Compose publishes four ports on the host:
3000 (web UI), 8080 (Go API, HTTP and WebSocket), 9090 (gRPC agent ingest) and
8428 (VictoriaMetrics). The generated admin password is printed once to the
API log on first boot (docker compose logs api | grep "Generated admin password"),
or set your own with KUBEBOLT_ADMIN_PASSWORD in deploy/.env before the
first up. Users, settings and metrics live in the kubebolt-data and
kubebolt-vm-data volumes, so they survive docker compose down (not
down -v). An agent in a local cluster (kind, Docker Desktop) dials
host.docker.internal:9090.
EKS note: The compose file mounts ~/.aws, but the API image it builds
does not include the AWS CLI, so kubeconfigs that run aws eks get-token
fail inside the container. For EKS, prefer the binary, Homebrew or the
single-container image (which ships aws-cli) — see the EKS guide.
Single Binary (macOS, Linux, Windows)
One executable with embedded frontend. API + UI in a single process on one port. Download from GitHub Releases.
# macOS Apple Silicon
curl -LO https://github.com/clm-cloud-solutions/kubebolt/releases/latest/download/kubebolt-darwin-arm64
chmod +x kubebolt-darwin-arm64 && sudo mv kubebolt-darwin-arm64 /usr/local/bin/kubebolt
# Linux amd64
curl -LO https://github.com/clm-cloud-solutions/kubebolt/releases/latest/download/kubebolt-linux-amd64
chmod +x kubebolt-linux-amd64 && sudo mv kubebolt-linux-amd64 /usr/local/bin/kubebolt
# Run (reads every context in the kubeconfig; admin password printed once to the log)
kubebolt --kubeconfig ~/.kube/config
Open http://localhost:8080 (--port changes it, --open opens the browser)
and log in as admin. The binary keeps users and settings in ./data,
relative to the directory you start it from (KUBEBOLT_DATA_DIR moves it), and
listens for agents on gRPC port 9090.
Available for darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, and windows-amd64 (kubebolt-windows-amd64.exe), plus the kubebolt-mcp stdio server for each platform; the .tar.gz / .zip archives are the krew packages. To verify a download, fetch CHECKSUMS.txt from the same release and run sha256sum --ignore-missing -c CHECKSUMS.txt (macOS: shasum -a 256 --ignore-missing -c CHECKSUMS.txt).
The single binary (like Homebrew, krew and the single-container image) does
not bundle a time-series store. Live views work without one. For history, it
looks for a VictoriaMetrics on http://localhost:8428 — run one there, point
KUBEBOLT_METRICS_STORAGE_URL at another, or use the
Compose stack or the Helm chart.
History also needs an agent shipping samples
(Connecting Clusters).
.env support: The binary auto-loads a .env file from the directory you start it in. Put KUBEBOLT_ADMIN_PASSWORD, KUBEBOLT_AI_API_KEY, etc. there. System env vars and CLI flags take precedence; every variable is in Environment variables.
To build your own binary from a checkout instead of downloading a release:
make build-binary
# Produces apps/api/kubebolt (embedded frontend)
Running from source for development is documented once, in Contributing.
Homebrew (macOS, Linux)
Install and update via Homebrew. It installs the same release binary as a cask, on macOS and Linux (amd64 + arm64).
# Install from the CLM tap
brew install clm-cloud-solutions/tap/kubebolt
# Run — then open http://localhost:8080
kubebolt --kubeconfig ~/.kube/config
# Update to the latest version
brew upgrade kubebolt
Everything in the single binary section applies: port, data directory, history.
Docker (single container)
Single image with embedded frontend. No nginx, no compose. Multi-arch (amd64/arm64).
docker run -p 3000:3000 \
-v ~/.kube/config:/kubeconfig:ro -e KUBECONFIG=/kubeconfig \
ghcr.io/clm-cloud-solutions/kubebolt:latest
Open http://localhost:3000 and log in as admin with the password printed
in the container’s log (docker logs <container> | grep "Generated admin password"),
or pass your own with -e KUBEBOLT_ADMIN_PASSWORD=…. Images are tagged
latest, 2.7 and 2.7.0; pin one in anything you keep.
The image runs as a non-root user (kubebolt), so mounting ~/.kube onto
/root/.kube does not work — the process can’t read /root. Mount the file
and point KUBECONFIG at it, as above. On Linux the kubeconfig file must be
readable by that user. A kubeconfig that points at 127.0.0.1 (Docker
Desktop, kind) reaches the container itself, not your cluster — see the
Docker Desktop guide. The embedded database lives in the /data volume;
mount one (-v kubebolt-data:/data) if you want users and settings to survive
a container restart. To let agents connect, publish their port too
(-p 9090:9090).
The image is signed with Cosign. Verify with:
cosign verify ghcr.io/clm-cloud-solutions/kubebolt:latest \
--certificate-identity-regexp 'https://github.com/clm-cloud-solutions/kubebolt/.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
EKS note: The image includes aws-cli. For EKS clusters, mount your AWS config into the non-root user’s home (-v ~/.aws:/home/kubebolt/.aws:ro) and set AWS_PROFILE if you use one, so the kubeconfig’s aws eks get-token exec can obtain tokens.
kubectl Plugin (krew)
Run KubeBolt as a kubectl subcommand. Available via CLM’s custom krew index.
# Prerequisite: install krew (one-time)
# https://krew.sigs.k8s.io/docs/user-guide/setup/install/
# Add the CLM custom index
kubectl krew index add clm https://github.com/clm-cloud-solutions/krew-index.git
# Install
kubectl krew install clm/kubebolt
# Run (uses your kubeconfig; serves http://localhost:8080, Ctrl+C stops it)
kubectl kubebolt
# Update
kubectl krew upgrade clm/kubebolt
Not built yet
Three more distribution methods are designed but not shipped. There is no URL to give you for any of them yet — when one lands it gets a section above, not a placeholder here.
- One-line install script. A
curl … | shthat detects OS and architecture and drops the binary in place. No such script exists in the repository today; until it does, use the single binary download or Homebrew. - Official krew-index. Once
kubeboltis accepted upstream intokubernetes-sigs/krew-index,kubectl krew install kubeboltwill work without adding the CLM custom index. Until then, use the custom index above. - Kubernetes Operator. Declarative lifecycle management through a
KubeBoltCRD in a separate Kubebuilder controller, handling upgrades and self-healing. Today the Helm chart is the supported in-cluster lifecycle.
Track these on the public roadmap.
Next
Once KubeBolt is up, connect your clusters — kubeconfig, the outbound-only agent, or metrics-only.