servchart-agent

The agent for ServChart, a self-hosted map of your servers, containers and Compose stacks.

It reads this host's Docker state (GET requests only), drops anything sensitive, and sends it to your ServChart hub every 60 seconds. It has no dependencies beyond Python's standard library.

Run it

With Docker (recommended):

docker run -d --name servchart-agent --restart unless-stopped --pid host \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /:/host:ro,rslave -e SERVCHART_HOST_ROOT=/host \
  -e SERVCHART_OBSERVE_CONNECTIONS=1 \
  -e SERVCHART_HUB=https://servchart.example.com \
  -e SERVCHART_TOKEN=sc_... \
  opticodev/servchart-agent:latest

Without Docker, from PyPI. The user running it needs access to the Docker socket, for example by being in the docker group:

pipx install servchart-agent        # or: pip install servchart-agent
servchart-agent --hub https://servchart.example.com --token sc_...
servchart-agent --stdout            # print what would be sent, send nothing

Get the token from the hub: + Add host in the map.

What it sends

It sends container names, images, state and health, networks and IPs, published ports, mounts, restart policy, and Compose stack details (project, service, folder, compose files). It never sends environment variables or container commands, and secret-looking label values are redacted. Set SERVCHART_HIDE_PATHS=1 to also drop host paths and stack folders.

Since 0.4 it also reports server health (CPU, memory, load, uptime, disk usage of each mount point), per-container CPU and memory, Docker's disk use, and backup status files from /var/lib/servchart/status. After a backup job, record it with servchart-agent --mark NAME (add --failed when it failed).

All options are in the main README.