← Documentation

Connecting clusters

Kaja works with your own infrastructure. You bring your clusters; we don't sell or host them. You connect each cluster to Kaja so you can develop and deploy from one dashboard—environments, apps, logs, metrics. This page explains how to add your 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 a name (e.g. "Staging", "Prod in AWS")—a label you'll recognize. Kaja generates a unique resource id for the cluster, same as for other resources in the app.
  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 its ongoing connection.

Run the command on your cluster

  • If you're creating new infrastructure (e.g. with k3d), create it, 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 (make sure your terminal is pointing at it).

After the agent is running, Kaja lists the cluster and shows it as Active when it's 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—so there's no long-lived secret that could be stolen or leaked. The agent then uses a refresh token for its ongoing connection to Kaja. You don't type the token yourself—Kaja generates it when you add the cluster 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 cluster 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 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. Your infra, one place to develop and deploy.

What you can do next

Once a cluster is connected you can:

  • Create environments (e.g. staging, prod).
  • 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 from sign-in to first connected cluster.
  • Installation — What the agent does and how the install command works.