Installation
Kaja has two parts: the dashboard you log into, and a small agent that runs on your infrastructure. You bring the clusters; we don't sell you infra. The agent is what lets you create projects, deploy apps, and read logs and metrics from Kaja against the clusters you connect. This page covers getting the agent onto a cluster and what it needs.
The CLI does both halves
Connecting a cluster used to be two steps in two places: register it in the dashboard, then paste a command carrying its token. Now it is one:
kaja cluster attachThe CLI registers the cluster and installs the agent in the same process, which is why there is no token to copy. The agent token is created, used, and discarded without ever being displayed or written down — Kaja stores only its hash, so the plaintext genuinely exists nowhere else.
That also means a cluster cannot end up registered with no agent, which was the most common way setup used to go wrong.
What you need
The requirement depends on what you are connecting.
| You have | Command | Needs |
|---|---|---|
| A Kubernetes cluster | kaja cluster attach | A kubeconfig context pointing at it |
| A container runtime | kaja cluster create | Docker, OrbStack, colima or Podman, running |
| A Linux server | kaja cluster create --dedicated | Root on the machine, and systemd |
| A Linux server, set up from here | kaja cluster create --ssh root@host | SSH access to it |
You do not need kubectl or Helm installed — the CLI talks to Kubernetes directly. Kaja never installs a container runtime for you; if none is running it names which to install.
For anything with a volume — PostgreSQL, durable Redis, metrics and logs — the cluster also needs a working default StorageClass. See Cluster requirements.
What it installs
Into the cluster: cert-manager, if it is not already there, and the Kaja agent into the kaja namespace. Both are Helm releases, so helm list -A shows them and re-running is how you upgrade.
Onto a dedicated machine, additionally: k3s as a systemd service. Everything written to the machine is recorded in /var/lib/kaja/install-manifest.json, so it can be removed exactly:
kaja cluster detach <name> --purge --dry-runThat prints the precise list before anything is removed. Without --dry-run it performs exactly that list, and never touches a file that was already there or that changed after Kaja wrote it.
Check that it worked
kaja cluster attach waits for the agent to connect and tells you when it has. To look for yourself:
kaja cluster lsIf a cluster stays disconnected, the agent could not reach Kaja: it dials out over gRPC on 443, so an egress firewall or proxy is the usual cause. Every install also writes a full transcript to ~/.kaja/logs/, with the agent token redacted, and a failing step names it.
If you deploy with GitOps
To manage the agent from a repository rather than letting the CLI install it:
kaja cluster attach --print-valuesThat registers the cluster and prints a complete Helm values file including its token, instead of installing anything. Apply it with the chart however you normally would. It is the one path where the token is displayed, because there is no other way to get it into your repository.
Next steps
- Connecting clusters — Add more clusters; each gets its own token.
- Cluster requirements — What a cluster needs before services will run.
- Sync & agents — How the agent and the dashboard stay in step.