Docker Standalone Agent

Run the KubeWatch agent as a standalone Docker container on any host.

The standalone Docker agent is the quickest way to monitor a single host running Docker. It requires only the Docker CLI, no Compose or orchestration needed.

Run the agent

docker run -d \
  --name kubewatch-agent \
  --restart unless-stopped \
  --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -e KUBEWATCH_API_KEY=YOUR_API_KEY \
  -e KUBEWATCH_AGENT_NAME=my-server \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v kubewatch-agent-data:/data \
  -v /proc:/host/proc:ro \
  -v /:/host/root:ro \
  ghcr.io/lloyd-theophilus/kubewatch-agent:latest

Replace YOUR_API_KEY with the key from Settings → API Keys (a kw... value, not a kwl_ent_... license key) and my-server with a name that will appear in the dashboard, for example prod-db-host or staging-web.

Flags that matter:

--group-add "$(stat -c '%g' /var/run/docker.sock)" grants the container the host's docker group so the non-root agent can read the (read-only) Docker socket. Without it the agent logs dial unix /var/run/docker.sock: connect: permission denied.
-v kubewatch-agent-data:/data persists the agent's identity (ID and token) across restarts. Without it the agent re-registers on every restart, creating duplicate agents and losing buffered metrics.
-v /proc:/host/proc:ro and -v /:/host/root:ro are optional: they let the agent collect this host's own system-level stats (load average, memory/swap, CPU%, disk throughput, filesystem usage, uptime) for the Overview page's Host Metrics dashboard. Without them, everything else still works. The agent just logs a harmless repeating host metrics collection error: open /host/proc/net/dev: no such file or directory line and skips this host's own stats.

For a self-hosted KubeWatch, also add `-e KUBEWATCH_SERVER_URL=https://your-domain` (or `http://` for a bare-IP install). For KubeWatch Cloud, omit it since the hosted endpoint is built into the agent.

Verify the agent is running

docker logs kubewatch-agent

Expected output within a few seconds:

2026/09/08 15:04:05 registered as agent agent_abc123
2026/09/08 15:04:05 starting initial collection (interval=15s)

A successful push isn't logged, only failures are, so no further output for a while is normal. Confirm data is actually arriving in the dashboard's agent selector.

Check the container is still up:

docker ps --filter name=kubewatch-agent

Environment variables

Variable	Required	Default	Description
`KUBEWATCH_API_KEY`	Yes	None	API key from dashboard Settings
`KUBEWATCH_AGENT_NAME`	No	system hostname	Display name shown in dashboard
`KUBEWATCH_INTERVAL`	No	`15s`	Metrics push interval (Go duration, e.g. `15s`, `1m`)

Update the agent

To update to the latest version:

docker pull ghcr.io/lloyd-theophilus/kubewatch-agent:latest
docker stop kubewatch-agent
docker rm kubewatch-agent
# re-run the docker run command above

Stop and remove

docker stop kubewatch-agent
docker rm kubewatch-agent

The agent will disappear from the dashboard after it stops sending data (shown as disconnected after ~60 seconds).