KubeBolt docs
ENES GitHub

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
  1. Helm Chart (recommended for Kubernetes)
  2. Docker Compose
  3. Single Binary (macOS, Linux, Windows)
  4. Homebrew (macOS, Linux)
  5. Docker (single container)
  6. kubectl Plugin (krew)
  7. Not built yet
  8. Next

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

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.

Track these on the public roadmap.

Next

Once KubeBolt is up, connect your clusters — kubeconfig, the outbound-only agent, or metrics-only.