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 that Kaja installs in each cluster when you run the install command from the cluster setup page. 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 an environment, 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. Each cluster has its own install command and a one-time token (shown on the setup page when you add that cluster). You run the install once; the agent uses that token to register with Kaja. Once consumed, that token is invalid—it can't be reused, so there's no long-lived secret to steal. The agent then uses a refresh token for its ongoing connection to Kaja.
• The agent runs in a 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 an environment, deploy a Helm app). Kaja sends that intent to the agent in the right cluster. The agent applies it—creates the namespace, runs Helm, 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 to stream logs or fetch pod metrics. The agent reads from the cluster (e.g. pod logs, metrics-server) and sends the data back so you see it in the console. So logs and metrics also go through the agent—that’s why they’re only available when the cluster is connected and the agent is running.

For more detail, see Logs & metrics.

What you need to do

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

1. Add the cluster in Kaja (enter a name; Kaja generates the cluster id and shows the setup page).
2. Run the install command on that cluster. The agent uses the one-time token from the command to register; once used, that token is invalid.
3. Use Kaja as usual—create environments, 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.