HarborForge.Monitor/README.md

HarborForge.Monitor

Lightweight Go telemetry client that reports server hardware status to the HarborForge backend.

Part of the HarborForge platform.

• Role: standalone telemetry agent; does not depend on OpenClaw, suitable for plain Linux hosts, VPS, Nginx boxes, etc.
• Reports to the HarborForge backend (POST /monitor/server/heartbeat).
• Optional local bridge HTTP server on 127.0.0.1:<MONITOR_PORT> (default port 9100) for the HarborForge OpenClaw plugin.

Collected Metrics

• CPU usage (cpu_pct)
• Memory usage (mem_pct)
• Disk usage (disk_pct, for the root / rootFs filesystem)
• Swap usage (swap_pct)
• Load average (load_avg — 1/5/15 min)
• Uptime (uptime_seconds)
• Nginx installed (nginx_installed)
• /etc/nginx/sites-enabled listing (nginx_sites)

When OpenClaw metadata has been pushed to the bridge, heartbeats are additionally enriched with openclaw_version, plugin_version, and agents.

Reporting Endpoint

The client sends:

• POST <backendUrl>/monitor/server/heartbeat
• Header: X-API-Key: <apiKey>
• JSON body: the telemetry payload described above

Project Structure

HarborForge.Monitor/
├── cmd/harborforge-monitor/      # Program entry point (main.go)
├── internal/config/              # Config loading (file + env + flags)
├── internal/telemetry/           # Metric collection and reporting
├── internal/bridge/              # Local MONITOR_PORT bridge server
├── systemd/                      # systemd unit file
├── Dockerfile                    # Container build
├── docker-compose.yml            # Docker Compose configuration
├── config.example.json
└── README.md

Configuration

First register the server in the HarborForge backend and generate an API Key.

Then prepare a config file, e.g. /etc/harborforge-monitor/config.json:

{
  "backendUrl": "https://monitor.hangman-lab.top",
  "identifier": "vps-nginx-01",
  "apiKey": "your-api-key",
  "reportIntervalSec": 30,
  "logLevel": "info",
  "rootFs": "/host",
  "monitorPort": 9100
}

Resolution order is: defaults → config file → environment variables → command-line flags (later wins). apiKey is required; the process exits if it is empty.

Environment Variables

Both the (intentionally compatible) HF_MONITER_* spelling and the HF_MONITOR_* spelling are accepted; HF_MONITER_* is checked first.

Variable	Purpose	Default
HF_MONITER_BACKEND_URL / HF_MONITOR_BACKEND_URL	Backend base URL	https://monitor.hangman-lab.top
HF_MONITER_IDENTIFIER / HF_MONITOR_IDENTIFIER	Server identifier	hostname
HF_MONITER_API_KEY / HF_MONITOR_API_KEY	Server API key	(required)
HF_MONITER_REPORT_INTERVAL / HF_MONITOR_REPORT_INTERVAL	Report interval (seconds)	30
HF_MONITER_LOG_LEVEL / HF_MONITOR_LOG_LEVEL	Log level	info
HF_MONITER_ROOTFS / HF_MONITOR_ROOTFS	Host root filesystem mount (for container use)	(empty)
MONITOR_PORT / HF_MONITOR_PORT	Local bridge port (0 = disabled)	0

When rootFs is set, HOST_PROC / HOST_SYS / HOST_ETC / HOST_VAR / HOST_RUN are derived from it (if not already set) so that gopsutil reads host metrics instead of the container's.

Command-line Flags

-config string          Path to config file (default "/etc/harborforge-monitor/config.json")
-once                   Collect and send telemetry once, then exit
-print-payload          Print the payload JSON before sending
-dry-run                Collect telemetry but do not send it
-version                Print version and exit
-backend-url string     Override backend URL
-identifier string      Override identifier
-api-key string         Override API key
-report-interval int    Override report interval in seconds
-log-level string       Override log level
-rootfs string          Override root filesystem path
-monitor-port int       Override monitor bridge port

MONITOR_PORT — Plugin Bridge

When MONITOR_PORT (or monitorPort) is greater than 0, Monitor starts a local HTTP server on 127.0.0.1:<MONITOR_PORT> for the HarborForge OpenClaw plugin to query telemetry.

Endpoint	Method	Description
/health	GET	Health check; returns status, monitor_version, and identifier
/telemetry	GET	Returns the latest cached telemetry snapshot
/openclaw	POST	Receives OpenClaw metadata (version, plugin version, agents) from the plugin

After the plugin pushes metadata via POST /openclaw, Monitor attaches openclaw_version, plugin_version, and agents to subsequent heartbeats. If the plugin never pushes metadata, these fields are omitted and heartbeats are unaffected.

Important: the bridge is optional. If MONITOR_PORT is 0 or unset, the bridge does not start. Even if the bridge fails to start, heartbeat reporting continues normally (bridge errors are logged as non-fatal).

Local Development

go mod tidy
go build ./cmd/harborforge-monitor
./harborforge-monitor -config ./config.example.json -dry-run -once

Docker

Build the image:

docker build -t harborforge-monitor .

Docker Compose

export HF_IDENTIFIER=my-server
export HF_API_KEY=your-api-key
export MONITOR_PORT=9100

docker compose up -d

The compose file runs with network_mode: host and mounts the host root filesystem read-only at /host (the image defaults HF_MONITER_ROOTFS=/host).

Manual Docker Run

Run with the host rootfs mounted read-only so the container collects host metrics instead of its own:

docker run -d \
  --name harborforge-monitor \
  --restart unless-stopped \
  --network host \
  -v /:/host:ro \
  -e HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top \
  -e HF_MONITER_IDENTIFIER=my-server \
  -e HF_MONITER_API_KEY=your-api-key \
  -e HF_MONITER_ROOTFS=/host \
  -e MONITOR_PORT=9100 \
  harborforge-monitor

systemd

You can also run the compiled binary via systemd:

go build -o /usr/local/bin/harborforge-monitor ./cmd/harborforge-monitor

cp systemd/harborforge-monitor.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now harborforge-monitor

The provided unit runs harborforge-monitor -config /etc/harborforge-monitor/config.json as root with Restart=always.