KubeBolt docs
ENES GitHub

Getting Started

Getting started on Cloud

Sign up at app.kubebolt.io, confirm your email, and connect your first cluster with the first-cluster wizard — one block to paste.

On this page
  1. 1. Create your account
  2. 2. Confirm your email — before you connect a cluster
  3. 3. Connect your first cluster
  4. 4. What “working” looks like
  5. Next

This is the path from nothing to a cluster on screen at app.kubebolt.io. Nothing to host — you install one agent in your own cluster and it dials out. What Cloud is and how it differs from self-hosting is KubeBolt Cloud.

1. Create your account

Start at app.kubebolt.io/signup. Signing up creates a user and an organization in one step, and you are that organization’s Admin. Two ways in:

A new organization starts on the Free plan: 2 clusters, 10 nodes, 150 pods, 3 users, 15 days of history and 100 AI credits a month. Free limits are hard caps — nothing is billed. Plans and what each includes are on Pricing; Administration → Billing shows yours.

2. Confirm your email — before you connect a cluster

Connecting a cluster requires a confirmed email. The step that issues the agent’s ingest token is gated on it — as are Kobi chat, inviting users, creating teams and issuing API tokens. If you open the cluster wizard first, it stops at the install step with “Confirm your email to get your install command” and there is nothing to paste. Confirm in another tab and the step continues on its own.

If you signed up with Google, Microsoft or GitHub, your email is already confirmed — the provider vouched for it, and KubeBolt records that at signup. There is nothing to do; go to step 3.

If you signed up with email and password, a banner across the top of the app reads “Confirm your email — we sent a code to …”. The email carries a link and a six-digit code:

  1. Open the link. It opens a KubeBolt page that asks for the code.
  2. Enter the code from the same email. After five wrong codes that link stops accepting any; send a new email.

A banner that says “Email delivery isn’t configured on this install” never appears on Cloud: it means a self-hosted multi-organization deployment whose SMTP is unset.

3. Connect your first cluster

Right after signup you land on a welcome page, “Your first cluster, live in about two minutes”. It lists what you need:

Connect my cluster opens the first-cluster wizard. No cluster at hand? Try it on your laptop opens the same wizard with a kind, k3d or minikube command first. Someone else installs it? Invite them goes to Administration → Access. Skip for now takes you to Home, whose Connect cluster button opens the same wizard later (so does Fleet → Connect cluster while the organization has no cluster).

The wizard has three steps:

  1. Name it. How the cluster shows up in KubeBolt — letters, numbers, dots, dashes and underscores; you can rename it later. Choose A cluster I already have or A cluster on my laptop.

  2. Install. The wizard issues an ingest token for your organization and hands you one install block with the token already inside. The token is shown once; Copy all copies the real value even while it is masked on screen. If no agent uses it within 7 days it stops working, and the wizard says until when; once an agent has used it, it keeps working. Run the block in a terminal where kubectl points at the cluster. It looks like this — copy yours from the wizard, which carries your token and cluster name:

    kubectl create namespace kubebolt-system --dry-run=client -o yaml | kubectl apply -f -
    kubectl -n kubebolt-system create secret generic kubebolt-agent-token \
      --from-literal=token=<your-token> --dry-run=client -o yaml | kubectl apply -f -
    helm upgrade --install kubebolt-agent oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
      --namespace kubebolt-system --create-namespace \
      --set backendUrl=agent.kubebolt.io:443 \
      --set cluster.name=<your-cluster-name> \
      --set rbac.mode=reader \
      --set tls.enabled=true \
      --set hubble.enabled=false \
      --set auth.mode=ingest-token \
      --set auth.ingestToken.existingSecret=kubebolt-agent-token

    The token goes into a Secret, never into the Helm values. The block is safe to run twice: apply replaces the Secret and upgrade --install updates the release. rbac.mode=reader gives KubeBolt a full read-only view of the cluster; changes (scale, restart, exec, edit) need operator — see RBAC mode.

  3. Go live. Click I ran it and the wizard waits for the agent (next section).

Advanced setup, linked from the wizard, opens the full Add cluster wizard: RBAC level, Hubble, Prometheus, OpenCost, resources, and which team owns the cluster. Opened from the first-cluster wizard, it reuses that wizard’s token, name and team instead of issuing a second token, and Back to the simple setup returns to it. Opened on its own, it issues the token separately — you tick “I’ve copied and saved the token — it can’t be shown again”, run its kubectl command to create the Secret, then its helm install command.

A cluster always registers with a team. A token issued without one is given your organization’s only team; with several, yours when you belong to exactly one, otherwise the organization’s default team. Unassigned stays an explicit choice in Advanced setup and Agent Tokens, whose Owner team pickers start on Automatic. Once your organization has a cluster, Connect cluster and Add cluster open a menu whose Install agent entry is this wizard. Every option it sets is described in Connecting Clusters. On Cloud, always install the agent: Import kubeconfig needs KubeBolt to dial your API server, and our backend has no route into your network.

4. What “working” looks like

After I ran it, the wizard checks for the new cluster every few seconds and shows “<name> is connected” with an Open <name> button the moment the agent registers — usually within a couple of minutes, image pull included. It never gives up: past five minutes it checks less often, and Close — keep it running only closes the window. The cluster shows up on Home whenever the agent connects.

Then, in order:

After two minutes without the agent, the wizard shows what to check:

kubectl -n kubebolt-system get pods
kubectl -n kubebolt-system logs ds/kubebolt-agent --tail=20
What you seeWhat it means
Nothing in kubebolt-systemkubectl was pointing at another cluster. Switch context and run the block again
Pods stuck in ContainerCreating, and kubectl -n kubebolt-system describe pod says secret "kubebolt-agent-token" not foundThe Secret line didn’t run. Run the whole block again
Log lines shipper session ended, will reconnect with a timeout or connection refusedThe cluster can’t reach agent.kubebolt.io:443. Open egress to it
cluster cap reached (2/2) for plan "free" in the logYour organization already has as many clusters as its plan allows. Delete one under Clusters, or change plan

Everything else is in Troubleshooting.

Next