Multiple Hosts / Agents

One KubeWatch organization can have an unlimited number of agents (subject to your plan's agent limit). Each agent is a separate process running on a different host, cluster, or environment, and they all report into the same dashboard.

How it works

All agents belonging to your organization use the same API key. The key identifies your organization, and the agent name distinguishes individual agents from each other.

API key: kw_live_abc123...
│
├── Agent: prod-k8s        (Kubernetes cluster, production)
├── Agent: staging-k8s     (Kubernetes cluster, staging)
├── Agent: prod-db-host    (bare-metal PostgreSQL server)
└── Agent: dev-compose     (developer laptop, docker-compose)

All four agents appear in the dashboard's agent selector, and you can switch between them or view an aggregated cluster summary.

Naming your agents

Set the KUBEWATCH_AGENT_NAME environment variable when starting each agent. Choose names that are descriptive and consistent.

Recommended naming convention:

{environment}-{platform}-{role}

Examples:

• prod-k8s-web, production Kubernetes, web tier
• prod-vm-db, production VM, database host
• staging-compose, staging Docker Compose stack
• dev-local, local development machine

Deploying to multiple hosts

Run the same agent command on each host, changing only the name:

Host 1 (production web server):

docker run -d \
  --name kubewatch-agent \
  --restart unless-stopped \
  -e KUBEWATCH_API_KEY=YOUR_API_KEY \
  -e KUBEWATCH_AGENT_NAME=prod-web \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/lloyd-theophilus/kubewatch-agent:latest

Host 2 (staging database server):

docker run -d \
  --name kubewatch-agent \
  --restart unless-stopped \
  -e KUBEWATCH_API_KEY=YOUR_API_KEY \
  -e KUBEWATCH_AGENT_NAME=staging-db \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/lloyd-theophilus/kubewatch-agent:latest

Agent limits by plan

If you exceed your plan's agent limit, additional agents will be rejected at registration until you upgrade or, on Enterprise, pay the per-agent overage rate shown in the error. Upgrade your plan in Settings → Billing to add more agents.

Viewing agents in the dashboard

The top bar of the dashboard has an agent selector dropdown. Select a specific agent to scope all views (containers, pods, nodes, alerts) to that agent. Select All agents to see a combined view.

Each agent is shown with:

• Name and ID
• Last seen timestamp
• Agent version
• Connected / Disconnected status