wiki / noc-homelab / agentsedited 2026-07-19
Agent API

Each machine runs a small Flask agent exposing a uniform HTTP API over Tailscale. The dashboard is just a client of these agents — every machine answers the same questions the same way, whether the service behind it is a systemd unit, a LaunchAgent, or a Docker container.

Endpoints

GET /api/agent/healthLiveness probe.GET /api/agent/infoAgent + platform metadata.GET /api/agent/machineHost stats — uptime, load, disk.GET /api/agent/servicesThe service registry with current state.GET /api/agent/statusOnline/offline for every registered service.POST /api/agent/service/<action>start · stop · restart · logs, with the service id in the JSON body.

Unknown services 404; unknown actions 400. The logs action takes an optional line count and returns the service’s recent output.

Service registry

Each agent reads a config.yaml describing its host’s services: an id, a label, and how the service is managed. Platform handlers translate the uniform API onto the native service manager — systemctl on Linux, launchctl on macOS, the Docker API for containers. Adding a service to a machine is one YAML entry; the dashboard picks it up on the next poll.

The public status feed described in status API is an allowlisted projection of what these agents report.