← Documentation

Connecting clusters

Kaja is built so you can see and manage all your Kubernetes clusters from one dashboard. Each cluster you add runs its own agent and gets its own secret token. This page explains how to add clusters and what to expect.

How to add a cluster

  1. In the Kaja app, open your organization and go to Clusters.
  2. Click Connect Cluster.
  3. Enter:
    • Name — A label you’ll recognize (e.g. “Staging”, “Prod in AWS”).
    • Slug — A short, unique id (e.g. staging, prod-aws). This is used in the install command and can’t be changed later.
  4. Submit the form.

Kaja creates the cluster and shows you a setup page. On that page you’ll see the exact install command for this cluster, including its token. No two clusters share the same token.

Run the command on the right cluster

  • If you’re creating a new cluster (e.g. with k3d), create it with the same slug you used in Kaja, then run the install command against that cluster.
  • If you’re connecting an existing cluster, make sure your terminal is using that cluster (check with kubectl config current-context), then run the install command.

After the agent is running, Kaja will list the cluster and show it as Active when it’s healthy.

Why the token matters

The install command includes a secret token. It ties that cluster to your Kaja account and organization. Keep it private. If someone else gets it, they could connect a cluster to your Kaja org. You don’t type the token yourself—Kaja generates it when you create the cluster and bakes it into the command.

Adding more clusters

You can connect as many clusters as you need. For each one:

  1. Connect Cluster → enter name and slug.
  2. Use the setup page to run the install command on that cluster.
  3. The new cluster appears in the sidebar and in the cluster list.

All clusters in the same organization show up in one place. You switch between them in the UI; each can have its own environments and apps.

What you can do next

Once a cluster is connected you can:

  • Create environments (e.g. staging, prod) to organize workloads.
  • Deploy container apps and Helm apps.
  • Pause environments or apps when you’re not using them to save cost.

Next steps

  • Quick start — End-to-end flow from sign-in to first connected cluster.
  • Installation — What the agent is and how the install command works.