← Documentation

Connecting clusters

Kaja works with your own infrastructure. You bring your clusters; we don't sell or host them. Connect each one to Kaja so you can develop and deploy from one dashboard — projects, apps, logs, metrics. This page explains how to add your clusters and what to expect.

Kaja runs on Kubernetes. Each cluster you connect is a standard Kubernetes cluster — managed cloud (EKS/GKE/AKS), on-prem, k3s, or a local k3d cluster for trying things out. See Architecture for how Kaja's concepts map to Kubernetes.

What you need

  • A Kubernetes cluster to connect (or a way to create one — k3d spins up a local cluster in seconds).
  • kubectl and Helm 3 on your machine, with kubectl pointing at the cluster you want to connect — you'll run one install command against it.
  • Permission to install into the cluster (the agent creates a namespace, default kaja, and runs there).

How to add a cluster

  1. In Kaja, open your organization and go to Clusters.
  2. Click Connect cluster.
  3. Enter a name (e.g. "Staging", "Prod AWS") — a label you'll recognize. Kaja generates a unique ID.
  4. Submit the form.

Kaja shows you a setup page with the exact install command for this cluster, including a one-time token. You run that command on your cluster; the agent uses the token once to register, then it's invalid. The agent then uses a refresh token for ongoing connection.

Run the command on your cluster

  • If you're creating new infrastructure, create it first, then run the install command from the setup page on that cluster.
  • If you're connecting existing infrastructure, run the install command on the cluster you want to connect.

After the agent is running, Kaja shows the cluster as Active when healthy. From then on you develop and deploy from the dashboard — on the infra you brought.

Secure registration: one-time token + refresh token

The install command includes a one-time token. The agent uses it once to register the cluster with your Kaja account; once consumed, that token is invalid and can't be reused — no long-lived secret to steal or leak. The agent then uses a refresh token for ongoing connection. You don't type the token yourself — Kaja generates it and bakes it into the command.

Adding more clusters

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

  1. Connect Cluster → enter a name; Kaja generates the ID and shows the setup page.
  2. Use the setup page to run the install command on that cluster.
  3. The cluster appears in the sidebar and cluster list.

All clusters in the same organization show up in one place. Switch between them in the UI; each can have its own projects and apps. Your infra, one place to develop and deploy.

What you can do next

Once a cluster is connected you can:

  • Create projects (e.g. staging, prod).
  • Deploy apps, and add managed services (databases, caches, tools) from the catalog.
  • Pause projects or apps when you're not using them to save cost.

Next steps

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