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
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:
- Email and password. Your name, email, an organization name, a country, and a password of at least 8 characters — every field is required. The email is your login. Tick I’m an individual / freelancer and the organization name is filled in from your own. Organization names are unique across KubeBolt Cloud — if yours is taken, the form says exactly that.
- Google, Microsoft, or GitHub. Sign in with the provider, then name your organization and pick a country. No password to choose. The provider must have verified your email address; if it hasn’t, the sign-in is refused.
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:
- Open the link. It opens a KubeBolt page that asks for the code.
- Enter the code from the same email. After five wrong codes that link stops accepting any; send a new email.
- The link and code are valid for 24 hours from signup. Resending does not extend that window.
- Resend email in the banner sends a fresh one, at most once every five minutes.
- Confirming in another tab clears the banner here — the app re-checks when the window gets focus again.
- If the 24 hours lapse, the app locks behind “Verify your email to continue” and a resend cannot help (every link expires on the same deadline). We send one reminder with a fresh link and code that opens a new 24-hour window; if it doesn’t reach you, contact support.
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:
- A Kubernetes cluster, and a terminal with
kubectlandhelmpointing at it. - Rights to create a namespace and a ClusterRole in that cluster.
- Outbound HTTPS from the cluster to
agent.kubebolt.io:443. Nothing dials in.
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:
-
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.
-
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
kubectlpoints 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-tokenThe token goes into a Secret, never into the Helm values. The block is safe to run twice:
applyreplaces the Secret andupgrade --installupdates the release.rbac.mode=readergives KubeBolt a full read-only view of the cluster; changes (scale, restart, exec, edit) needoperator— see RBAC mode. -
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:
- The cluster appears in Fleet and in the cluster switcher.
- Home counts it, with its nodes and pods.
- The cluster’s Overview renders live resources immediately. Historical charts need the agent to ship a few minutes of samples first, so a fresh cluster looks thin for its first minutes. That is normal, not a fault.
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 see | What it means |
|---|---|
Nothing in kubebolt-system | kubectl 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 found | The Secret line didn’t run. Run the whole block again |
Log lines shipper session ended, will reconnect with a timeout or connection refused | The cluster can’t reach agent.kubebolt.io:443. Open egress to it |
cluster cap reached (2/2) for plan "free" in the log | Your organization already has as many clusters as its plan allows. Delete one under Clusters, or change plan |
Everything else is in Troubleshooting.
Next
- Kobi Copilot —
⌘J. On Cloud the AI is managed and draws on your plan’s monthly AI credits; there is no key to configure and no enabling step. It needs a confirmed email. - Home and Fleet — the two screens you will live in.
- Security and compliance — what lights up once you install a scanner.