Watchdog has two ways of running checks:
/proc, the process list and the Docker socket.Which way a check type allows is listed in the check types overview.
The agent connects to the dashboard on its own and pulls its checks. No inbound port needs to be open on the monitored machine.
host-server or customer-acme.Each monitored machine gets its own agent and its own token.
The files compose.yml, compose.stage.yml and compose.live.yml already contain an agent service. It is built from the same Dockerfile (target agent), runs as user www-data and starts php bin/console watchdog:agent:run. It reaches the dashboard over the internal Docker network at http://app:80.
WATCHDOG_AGENT_TOKEN=... in .env.stage or .env.live. In the local stack compose.yml reads the variable from the shell environment or from the .env file next to the Compose file, Docker Compose does not read .env.local.docker compose -f compose.stage.yml up -d agent
On live use compose.live.yml, locally docker compose up -d agent.
The service at a glance (stage):
agent:
build:
context: .
target: agent
environment:
WATCHDOG_DASHBOARD_URL: http://app:80
HOST_ROOT: /host/root
TZ: Europe/Berlin
env_file: .env.stage # contains WATCHDOG_AGENT_TOKEN
pid: host # for the process check
volumes:
- /:/host/root:ro # for disk, file and log checks
# - /var/run/docker.sock:/var/run/docker.sock:ro # for Docker checks
restart: unless-stopped
The Docker socket is commented out in the Compose files. Enable the line so that Docker and Docker Exec run on the agent. Because the agent runs as www-data, it must be allowed to read the socket. Worker and scheduler solve this in the Compose files with group_add using the socket's group ID (DOCKER_GID, default 995). The agent needs the same entry when the socket is only accessible to the Docker group.
Dashboard checks of type Docker run in the worker container, which already has the socket mounted.
For another server (for example at a customer) there is a ready-made image that CI builds and publishes for the main branch and for release tags: ghcr.io/markus-michalski/watchdog/agent:latest (architectures amd64 and arm64).
Use docker-compose.agent.yml from the repository as a template:
services:
watchdog-agent:
image: ghcr.io/markus-michalski/watchdog/agent:latest
restart: unless-stopped
environment:
WATCHDOG_DASHBOARD_URL: https://watchdog.example.com
WATCHDOG_AGENT_TOKEN: your-agent-token-here
HOST_ROOT: /host/root
TZ: Europe/Berlin
pid: host
volumes:
- /:/host/root:ro
docker compose -f docker-compose.agent.yml up -d
The template in the repository does not set
HOST_ROOT. WithoutHOST_ROOT: /host/rootthe agent reads paths inside its own container instead of the host filesystem. Add the line as soon as you use disk, file or log checks.
The server must be able to reach the dashboard URL, preferably over HTTPS. WATCHDOG_DASHBOARD_URL has no trailing slash.
| Variable | Required | Meaning |
|---|---|---|
WATCHDOG_DASHBOARD_URL |
yes | Dashboard base URL without a trailing slash. http://app:80 in the Compose stack, the public HTTPS URL for remote agents |
WATCHDOG_AGENT_TOKEN |
yes | Token from the Register Agent flow |
HOST_ROOT |
for file, disk and log checks | Prefix prepended to the configured paths, usually /host/root |
TZ |
recommended | Time zone, for times in messages and the daily run time |
| Check type | Needed on the agent |
|---|---|
| Disk Space, File Age, File Size, Log File | Volume /:/host/root:ro and HOST_ROOT=/host/root |
| Process | pid: host |
| Docker, Docker Exec | Volume /var/run/docker.sock:/var/run/docker.sock:ro and read access to the socket |
| Load Average | nothing, reads /proc/loadavg |
| TCP Port, Redis, Database, DNS | nothing, the test runs from the agent's machine |
HTTP, HTTP Content and SSL Certificate are dashboard-only checks and cannot be assigned to an agent.
/api/v1/agent/config./api/v1/agent/run-now for manually requested runs and executes all checks that are due./api/v1/agent/results.The agent shuts down gracefully on SIGTERM and SIGINT. Start a test run without continuous operation with --run-once:
docker compose -f docker-compose.agent.yml run --rm watchdog-agent --run-once
An agent only receives active checks of active clients that are assigned to it and whose runner is Agent (Local). Interval and daily time apply as for dashboard checks, but the agent evaluates them locally and starts a check at the earliest once the interval minus 5 seconds has elapsed.
| Action | Effect |
|---|---|
| Edit Name | Renames the agent |
| Regenerate Token | Creates a new token. The old one stops working immediately, the agent needs the new token |
| Delete Agent | Removes the agent. Its checks remain but are detached from the agent and switched to the runner Dashboard (Network) |
After an agent is deleted its checks keep running in the dashboard's worker container. Agent-type checks such as disk or process then measure the dashboard container instead of the monitored machine. Assign them to another agent or deactivate them before deleting.
The agent's status in the UI is Online when it made contact within the last 10 minutes. Watchdog sends no notification when an agent fails, see Notifications.
For notes on permissions see Security and Privacy, for failure patterns see Troubleshooting.