📡 node-watch-agent

Lightweight Go metrics agent that collects CPU, vCPU, memory, and per-disk usage, then reports them to a ConnectRPC server.

The agent is designed to run headlessly without a local UI requirement, making it suitable for minimal VPS environments managed through configuration, service control, and a remote management server.

🗂️ Repository Structure

.
├── cmd/
│   └── node-watch-agent/        # CLI entrypoint
├── internal/
│   ├── client/                  # ConnectRPC metrics client
│   ├── collector/               # CPU, memory, host, and disk collectors
│   └── config/                  # YAML config loading and validation
├── proto/
│   └── metrics/
│       └── v1/                  # Metrics protobuf schema and generated Go code
├── scripts/
│   └── build-dist.ps1           # Local multi-platform release build script
├── .github/
│   └── workflows/               # CI and release artifact workflows
├── config.example.yaml          # Example runtime configuration
├── buf.yaml                     # Buf module configuration
├── buf.gen.yaml                 # Protobuf code generation configuration
├── go.mod
├── install.sh                   # Quick install script for Linux and macOS
├── how-to-install.md            # Package installation guide
└── README.md

⚙️ Configuration

Copy config.example.yaml to config.yaml and update the values:

server_url: "http://localhost:8080"
# Optional. Leave empty to use the machine hostname.
agent_id: "agent-001"
bearer_token: "replace-me"
interval: "10s"
cpu_collect_interval: "1s"
timeout: "5s"
disk_exclude_patterns:
  - "/proc/*"
  - "/sys/*"
  - "/dev/*"

agent_id identifies the machine in metrics reports. If it is empty or omitted, the agent uses the machine hostname. interval controls how often metrics are reported to the server. cpu_collect_interval controls how often CPU usage is sampled locally. The reported cpu.used_percent is the peak sampled CPU value since the previous report.

▶️ Run

See how-to-install.md for package installation steps.

go run ./cmd/node-watch-agent -config config.yaml

Quick run on a VPS does not require systemd. Place config.yaml next to the binary, then run:

./node-watch-agent -config config.yaml

When installed with install.sh, update /etc/node-watch-agent/config.yaml, then run:

sudo systemctl restart node-watch-agent.service

On Linux hosts with systemd, install.sh creates and starts node-watch-agent.service automatically.

To uninstall the agent and remove /etc/node-watch-agent:

curl -fsSL https://github.com/LaiXuanAn/node-watch-agent/releases/download/v0.1.0/uninstall.sh | sh

Dry run collects metrics and prints them to stdout without connecting to server_url (for example, without requiring a ConnectRPC server on localhost):

go run ./cmd/node-watch-agent -config config.yaml -dry-run

To collect metrics once in dry-run mode, add -once:

go run ./cmd/node-watch-agent -config config.yaml -dry-run -once

🗺️ Roadmap

• Monitor Docker runtime metrics, including per-container CPU, memory, network, and block I/O usage from Docker stats.
• Report Docker volume usage so operators can track persistent storage growth before disks become full.
• Add a secure live VPS command channel for remote administration, where the agent connects to the management server, keeps the command session alive, and automatically reconnects when the network or process is interrupted. Operators should only need to authenticate once instead of logging in again every time they reopen the management app.
• Add live Docker container controls, including running commands inside containers, viewing interactive output, and supporting common operational actions from the management server.

🤝 Contributing

Contributions are welcome. If you find bugs, missing metrics, unclear setup steps, or OS-specific issues, please open an issue or submit a pull request.

This project aims to stay lightweight, reliable, and easy to run on small servers. Good-faith help to update, improve, test, document, or package the product is appreciated.

🔌 API

The agent sends metrics to:

/metrics.v1.MetricsService/ReportMetrics

Authentication uses:

Authorization: Bearer <token>

Current request JSON fields sent to the server:

{
  "agentId": "agent-001",
  "hostname": "server-01",
  "os": "linux",
  "collectedAt": "2026-07-29T12:34:56Z",
  "cpu": {
    "usedPercent": 12.5,
    "vcpuCount": 4
  },
  "memory": {
    "totalBytes": "8589934592",
    "usedBytes": "4294967296",
    "freeBytes": "4294967296",
    "usedPercent": 50
  },
  "disks": [
    {
      "path": "/",
      "filesystem": "ext4",
      "totalBytes": "107374182400",
      "usedBytes": "53687091200",
      "freeBytes": "53687091200",
      "usedPercent": 50
    }
  ]
}

The response JSON is:

{
  "accepted": true,
  "message": "ok"
}