Connecting with kubectl

Once your hosted cluster is running, you connect to it with a kubeconfig you download from the dashboard (open the cluster, then the Kubeconfig tab). kubehz offers two kinds, and the default is the one you want.

Early access

The hosted control plane is in early access. This page describes how access works for a hosted cluster; for a self-hosted cluster you already hold your own kubeconfig.

The OIDC kubeconfig (default)

The default download is an OIDC kubeconfig. It carries no long-lived credential — instead it tells kubectl to sign you in through kubehz (the same login you use for the dashboard) and use that identity. Your access to the cluster follows your team membership and role: what kubectl can do is exactly what your role allows.

This is the recommended way to connect: nothing secret sits in the file, access tracks your live login, and if you leave the team your access ends with it.

One-time setup: install kubelogin

The OIDC kubeconfig uses the kubelogin plugin (kubectl oidc-login) to handle the browser sign-in. Install it once:

# krew (any platform)
kubectl krew install oidc-login

# or Homebrew (macOS / Linux)
brew install int128/kubelogin/kubelogin

Connect

1. In the dashboard, open your cluster and the Kubeconfig tab.

2. Download the OIDC kubeconfig (the default) and save it, e.g. to ~/.kube/kubehz-<cluster>.yaml.

3. Point kubectl at it and run any command:

   export KUBECONFIG=~/.kube/kubehz-<cluster>.yaml
   kubectl get nodes

   The first command opens your browser to sign in to kubehz. After that, the token is cached and kubectl works normally until it expires, when it simply asks you to sign in again.

If a command returns Forbidden, your role does not grant that action — see Team & roles.

The admin kubeconfig (advanced, discouraged)

An admin kubeconfig is also available under an Advanced option, but we discourage it:

• it embeds a long-lived client certificate, not tied to your identity;
• it cannot be revoked short of rotating the cluster's CA;
• it always grants full cluster-admin, ignoring your role.

Reach for it only as a break-glass fallback (for example, if the OIDC path is unavailable). Because it is sensitive, it is double-gated:

1. Enable it first in the cluster's Settings — this requires a fresh two-factor sign-in and an explicit consent checkbox. Until you do, the admin download is unavailable.
2. Download — the download itself requires another fresh two-factor sign-in.

Every enable, disable, and download is recorded in your account audit log. Turn the option back off in Settings when you no longer need it.

Next steps

• Team & roles — what each member can do, and custom roles scoped to namespaces.
• Identity & sign-in — how your login maps to cluster access.
• Add-ons — the in-dashboard cluster viewer and other hosted add-ons.

---

Doc status

Aspect	Detail
State	early access — hosted access live
Last reviewed	2026-07-14