Agent Health¶

Campus WoL uses background services called agents to perform network operations. These agents run inside Docker containers and handle tasks like sending wake packets, scanning networks, and querying switches. If an agent goes offline, the features that depend on it will stop working.

This page explains what each agent does, how to check its status, and what to do when something is wrong.

What Are Agents?¶

Agents are small, specialized programs that run continuously in the background. Each agent is responsible for one type of network operation. They communicate with the main Campus WoL backend over Unix sockets, which means their traffic never leaves the host machine.

You do not interact with agents directly. The Campus WoL interface talks to the backend, and the backend delegates network operations to the appropriate agent.

Health Endpoints¶

Campus WoL exposes two health endpoints for checking system status:

Endpoint	Authentication	Purpose
`/api/dashboard/health`	Required (logged-in users)	Detailed health status of all agents and backend components
`/api/dashboard/healthz`	None (public)	Simple readiness probe that returns OK/not-OK, suitable for monitoring tools

The /api/dashboard/health endpoint reports the status of each individual agent, so you can see exactly which service is healthy and which is not.

The Three Agents¶

wol-agent¶

What it does: Sends magic packets to wake devices and transmits BenQ display power commands.

Impact if offline: All wake operations and display control will fail. This is the most critical agent for day-to-day operations.

scan-agent¶

What it does: Performs network discovery scans to find devices on a VLAN. Used when populating or updating the device inventory for a classroom.

Impact if offline: Discovery scans will not run. Existing device records are unaffected, but you cannot discover new devices or refresh MAC address information.

snmp-agent¶

What it does: Polls network switches using SNMP to map which devices are connected to which switch ports. This provides additional visibility into the physical network topology.

Impact if offline: Switch-to-port mapping data will not be available. Wake and scan operations are unaffected.

The snmp-agent is optional

The snmp-agent only starts when explicitly enabled using the snmp Docker profile. To start it, run:

docker compose --profile snmp up

If your deployment does not use SNMP, the snmp-agent will show as offline in the health endpoint. This is normal and expected. It does not indicate a problem.

Checking Agent Status¶

From the Health Endpoint¶

The quickest way to check agent health is to visit the /api/dashboard/health endpoint while logged in. It returns the status of each agent.

From the Command Line¶

If you have access to the server, you can check container status directly:

docker compose ps

This lists all running containers and their current state. A healthy agent will show a status of Up. A stopped or crashed agent will show Exited or will not appear in the list.

What to Do If an Agent Is Offline¶

Check the container status. Run docker compose ps to see whether the container is running, stopped, or restarting.
Review the logs. Check the agent's logs for error messages:
```
docker compose logs wol-agent
docker compose logs scan-agent
docker compose logs snmp-agent
```
Add --tail 50 to limit output to the most recent 50 lines, or --follow to watch logs in real time.
Restart the agent. If the container has stopped, restart it:
```
docker compose restart wol-agent
```
Check the health endpoint again after restarting to confirm the agent is back online.

Common Agent Issues¶

Socket permission errors. Agents communicate over Unix sockets. If the socket file has incorrect permissions, the agent will fail to connect to the backend. This typically happens after a manual file system change. Restarting the full stack with docker compose down && docker compose up -d usually resolves it.

Network interface not found. The wol-agent and scan-agent need access to the host's network interfaces. If the Docker container is not configured with the correct network mode or the expected interface name has changed, the agent will fail to start. Check the Docker Compose configuration to ensure the network settings match your host environment.