Sync & agents

When you use Kaja, you’re using a dashboard (the website) and a small agent that runs on your infrastructure—on each cluster you connect. You bring your own infra; the agent is what lets you develop and deploy from the dashboard. This page explains what the agent is, why it’s there, and what “sync” means from your point of view—without technical jargon.

What is the agent?

The agent is a component the Kaja CLI installs in each cluster when you run kaja cluster attach. It runs in the background and does two things that matter to you:

1. It carries out what you do in Kaja. When you create a project, deploy an app, or delete something, Kaja tells the agent on that cluster to do it. The agent makes it happen where your workloads run—so your actions in the dashboard become real on your infra.

2. It reports back what’s happening. The agent watches the cluster and sends status back to Kaja—so you see up-to-date pod counts, health, logs, and metrics in the console. When something fails or changes, you see it in Kaja.

So from your perspective: you act in the dashboard → the agent makes it happen in the cluster and keeps Kaja informed.

One agent per cluster

• You install one agent per cluster, and each has its own token. The token is the agent's whole identity, and it is what the agent presents on every connection — it does not expire and is not consumed by first use. Kaja stores only its hash, and the CLI creates and uses the plaintext in a single process, so it is never displayed or written down. Replace one with kaja cluster reconnect <name>, which reissues and reinstalls together.
• The agent runs in namespace (usually kaja) and stays connected to Kaja as long as the cluster is running and can reach the Kaja platform.

When the agent is running and healthy, Kaja shows the cluster as Active. If the agent stops (e.g. the pod is down or the cluster can’t reach Kaja), the cluster may appear disconnected until the agent is back.

What “sync” means for you

Sync here just means “Kaja and your cluster stay in step.”

• You do something in Kaja (e.g. create a project, add a managed service). Kaja sends that intent to the agent in the right cluster. The agent applies it—creates the namespace, runs the workload, etc. When it’s done (or if it fails), Kaja updates so you see the result.
• Something changes in the cluster (e.g. a pod restarts, a deployment becomes ready). The agent sees it and reports to Kaja. The dashboard then shows the latest status, pod list, and so on.

You don’t have to run any sync command yourself. As long as the agent is installed and the cluster is connected, this happens automatically.

Logs and metrics

When you open Logs or Metrics for an app, Kaja asks the agent in that app’s cluster for them. For the live view the agent reads directly from the pods. For searchable history and metrics over time it queries the Observability stores running in that same cluster, and only if you have installed them. Either way the data travels back over the agent’s connection, which is why logs and metrics are available only while the cluster is connected.

For more detail, see Logs & metrics.

What you need to do

From a user’s point of view you only need to:

1. Run kaja cluster attach with kubectl pointing at the cluster.
2. The CLI registers the cluster and installs the agent in the same run, so there is no token to move between them.
3. Use Kaja as usual—create projects, deploy apps, view logs and metrics. The agent handles the rest.

You don’t configure “sync” or “streams”—the agent and the platform handle that. If a cluster shows as Active, sync is working.

Summary

Next steps

• Installation — What the install command does and how to run it.
• Connecting clusters — Add clusters and get the install command for each.
• Logs & metrics — View logs and metrics for your apps.