Getting Started
Quick Start
Get KubeBolt running in under 2 minutes: install with the Helm chart or Docker Compose, get the admin password and finish the first-login Setup Wizard.
On this page
Fastest: Helm chart
You need kubectl pointing at the cluster, Helm 3 (3.14 or later for the
upgrade commands in these docs), and rights to create a namespace and a
ClusterRole.
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace --wait
kubectl -n kubebolt get secret kubebolt-admin-password \
-o jsonpath='{.data.password}' | base64 -d ; echo
kubectl -n kubebolt port-forward svc/kubebolt 3000:80
Open http://localhost:3000 and log in as admin with the printed password.
--wait returns once the pods are ready — by then the generated password is
already in its Secret — and the port-forward stays in the foreground
(Ctrl+C stops it). The chart deploys the API, the web UI and a single-node
VictoriaMetrics for history (10 GiB PVC, 30-day retention). Three pods should
be Running:
kubectl -n kubebolt get pods
# kubebolt-api-…, kubebolt-web-…, kubebolt-victoriametrics-0
You land on Home; pick the cluster to open its dashboard. KubeBolt watches the cluster it runs in through its own ServiceAccount; other clusters join through the agent (Connecting Clusters).
The chart needs a default StorageClass: it creates two PVCs, 10 GiB for
VictoriaMetrics and 1 GiB for KubeBolt’s own data (users, settings). AKS,
GKE, kind and k3s ship one. On EKS, install the EBS CSI driver add-on
first, or both PVCs stay Pending and --wait times out — see
Troubleshooting.
Live metrics vs. history
Out of the box you get live CPU and memory, read from Metrics Server — the
current value only. Everything over time — history charts, network flows,
the Cost tab — needs something shipping samples into the bundled
VictoriaMetrics: the agent, or a Prometheus remote_write once the
receiver is enabled (--set metrics.remoteWrite.enabled=true). Without one,
the history panels stay empty.
For the agent next to this install it is one more command — no token, it dials the in-cluster ingest Service:
helm install kubebolt-agent \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
--namespace kubebolt \
--set backendUrl=kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090
kubectl -n kubebolt get pods -l app.kubernetes.io/name=kubebolt-agent
One agent pod per node, Running; the history charts start filling within a
few minutes. Hubble network flows are off by default — add
--set hubble.enabled=true if the cluster runs Cilium with Hubble.
More sources (reading an existing Prometheus, managed Prometheus offerings) in Metrics.
Get the admin password
Authentication is on by default and the chart seeds an admin user on first
boot. There are three ways to learn the password, in order of usefulness:
1. Read the Secret. When KubeBolt runs in-cluster, the API persists the generated password to a Secret in its own namespace on first boot (only when it generated one — not when you set it yourself). This is the one you can read at any time:
kubectl -n kubebolt get secret kubebolt-admin-password \
-o jsonpath='{.data.password}' | base64 -d ; echo
2. Set it yourself at install time, so there is nothing to look up:
helm install kubebolt \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
--namespace kubebolt --create-namespace \
--set auth.adminPassword=YourSecurePassword
For production, keep it out of your shell history with an existing Secret
(auth.existingSecret, keys admin-password and jwt-secret) — see the
chart README or Authentication.
3. Read the log line. The same password is printed once, at first startup:
kubectl -n kubebolt logs deployment/kubebolt-api | grep "Generated admin password"
The log line is printed once, at first boot. If you missed it, read the Secret — do not reinstall. The Secret is only created on first boot, so it does not track later password changes. If you have forgotten a password you already changed, see the recovery paths in Authentication.
The first-login Setup Wizard
The first time an admin signs in with authentication enabled, KubeBolt opens a four-step overlay: Password, AI Copilot (Kobi, with your own API key), Agent, Notifications.
Every step is optional. “Next” always advances without saving; each step has
its own inline save button if you want to set that value now. The overlay is
deliberately not dismissable with Esc or an outside click — the only exit
is the Skip wizard button, present on every step. Skipping or finishing
marks it done, so it does not come back on your next login.
Nothing here is a gate. All four stay reachable afterwards: your password from the avatar menu → Change password, and the rest under Administration — AI (Kobi), Agents & Ingest, and System → Notifications.
Docker Compose
Compose runs KubeBolt from the git repository — the compose file and the kubeconfig helper are files in the repo, not published artifacts, so you clone first:
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; nginx in the web container proxies the API
and its WebSockets to the Go backend. Log in as admin with the password the
API prints once on first boot:
docker compose logs api | grep "Generated admin password"
The full Compose reference — ports, images, EKS credentials — lives in Installation methods.
Running KubeBolt from source instead? The local development setup is documented once, in Contributing.
Prefer the Cloud?
On KubeBolt Cloud there is nothing to host:
sign up, confirm your email, and the first-cluster wizard hands you one block
to paste — the agent, its token and the helm command — and your cluster is
live, with Kobi included from the Free plan. Step by step in
Getting started on Cloud.
Next
- Connecting Clusters — add another cluster with the outbound-only agent.
- Installation methods — every other way to run KubeBolt: Compose, single binary, Homebrew, container, krew.
- KubeBolt Cloud — if you would rather not host it.