Docker Compose Agent

If your application is already managed with Docker Compose, the easiest way to add KubeWatch monitoring is to append the agent service to your existing docker-compose.yml.

Add the agent service

Append the following to the services: block in your docker-compose.yml:

services:
  # ... your existing services ...

  kubewatch-agent:
    image: ghcr.io/lloyd-theophilus/monitoring/kubewatch-agent:latest
    restart: unless-stopped
    environment:
      KUBEWATCH_API_KEY: "${KUBEWATCH_API_KEY}"
      KUBEWATCH_AGENT_NAME: "my-stack"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

The agent mounts the Docker socket read-only, it only reads container state and stats.

Store the API key in .env

Add your API key to a .env file in the same directory as your docker-compose.yml:

# .env
KUBEWATCH_API_KEY=kw_live_abc123...

Docker Compose automatically reads .env and substitutes ${KUBEWATCH_API_KEY} in the compose file.

Start the agent

If your stack is already running, bring just the new service up without restarting everything else:

docker compose up -d kubewatch-agent

Or restart the full stack:

docker compose up -d

Verify the agent connected

docker compose logs kubewatch-agent

Look for:

INFO  agent registered, id=agent_abc123 name=my-stack
INFO  push ok, containers=5

Docker socket permissions

The agent needs read access to /var/run/docker.sock. On most Linux systems the socket is owned by the docker group. If the agent fails with a permission error, either:

• Run Docker Compose as root (sudo docker compose up -d)
• Or add your user to the docker group: sudo usermod -aG docker $USER (requires re-login)

Environment variables