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 \
  -e KUBEWATCH_API_KEY=YOUR_API_KEY \
  -e KUBEWATCH_AGENT_NAME=my-server \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  ghcr.io/lloyd-theophilus/monitoring/kubewatch-agent:latest

Replace YOUR_API_KEY with the key from Settings → API Keys and my-server with a name that will appear in the dashboard (e.g., prod-db-host, staging-web).

Verify the agent is running

docker logs kubewatch-agent

Expected output within a few seconds:

INFO  connecting to gateway=https://YOUR_KUBEWATCH_URL
INFO  agent registered, id=agent_abc123 name=my-server
INFO  push ok, containers=8
INFO  push ok, containers=8

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	`15`	Metrics push interval (seconds)
`KUBEWATCH_LOG_LEVEL`	No	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
`KUBEWATCH_TLS_SKIP_VERIFY`	No	`false`	Skip TLS cert verification (self-hosted with self-signed cert only)

Update the agent

To update to the latest version:

docker pull ghcr.io/lloyd-theophilus/monitoring/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).