Zeus daemon (zeusd)

zeusd is a system daemon that runs with admin privileges and exposes an HTTP API for GPU management and GPU/CPU power streaming. It lets unprivileged applications safely change GPU configuration without granting them SYS_ADMIN, and serves cluster-wide power readings over Server-Sent Events.

Full documentation: https://ml.energy/zeus/zeusd/

Why

Energy optimizers in Zeus need to change GPU configuration (power limit, clocks, persistence mode), which requires SYS_ADMIN on Linux or admin elevation on Windows. Granting an entire ML application those privileges is too much. zeusd runs as a single privileged process per node and exposes a minimal set of HTTP endpoints; unprivileged applications relay privileged calls through it.

zeusd also serves GPU and CPU power readings via SSE -- demand-driven, so hardware is only polled while a client is connected -- enabling cluster-wide power monitoring without giving every node-side process root.

Platform support

• Linux: UDS default. All API groups work (NVML + RAPL).
• Windows: named pipe default. NVML only; cpu-read is rejected at startup since RAPL is Linux-only. Python clients must use --mode tcp.

Install

cargo install zeusd

For a hardened systemd deployment, see packaging/systemd/.

Quick start

All three transports serve the same HTTP API:

# Unix domain socket (Linux default)
sudo zeusd serve --socket-path /run/zeusd/zeusd.sock --socket-permissions 666

# TCP (cluster-wide monitoring; required for Python clients on Windows)
sudo zeusd serve --mode tcp --tcp-bind-address 0.0.0.0:4938

# Windows named pipe (Windows default; from an elevated PowerShell)
zeusd serve --pipe-name \\.\pipe\zeusd

To let the Zeus Python library auto-detect the daemon, set one of:

export ZEUSD_SOCK_PATH=/run/zeusd/zeusd.sock     # UDS
export ZEUSD_HOST_PORT=node1:4938                # TCP

When set, NVIDIAGPUs and RAPLCPUs automatically relay privileged calls and CPU/DRAM reads through the daemon.

Testing

Unit and integration tests run via cargo test inside zeusd/. CI runs the matrix on every push.

For Windows-specific end-to-end coverage with a real NVIDIA GPU, two helper scripts live in zeusd/scripts/:

• test-windows-gpu.sh provisions a g4dn.xlarge on AWS, builds zeusd from a Git ref, runs TCP + named-pipe smoke tests, a PyTorch matmul load with NVML power-limit / locked-clocks round-trips, and an SDDL ACL test that drives privileged NVML writes from an unprivileged client through the elevated daemon. Tears its own resources down via a trap. Pass -h for options.
• cleanup-test-aws.sh lists or deletes resources tagged zeusd-test (used to recover from crashed traps or stale orphans on a shared AWS account). Default mode is list-only; deletion requires an explicit scope (--tag-value, --older-than, or --all). Pass -h for the full usage.

Both scripts require aws CLI v2 with valid credentials and jq. Resources are tagged with a unique per-run value (zeusd-test-<utc-second>-<pid>-<6 hex chars>), so concurrent runs by multiple devs on the same AWS account don't collide and a scoped cleanup affects only its own run.

Documentation

API groups (gpu-control, gpu-read, cpu-read), JWT authentication, Windows-specific behavior, the full HTTP API reference, troubleshooting, and Python client integration are all covered at https://ml.energy/zeus/zeusd/.