The Problem

Managing multiple VPS instances across different cloud providers is tedious. Logging into each server to check service status, SSL certificates, and resource usage doesn’t scale. I needed a way to monitor everything from a single dashboard.

The Solution: A Single Binary Agent

Nodestral Agent is a Go binary that runs on each node and reports back to a central API. Key design decisions:

Why Go?

• Single binary deployment — no runtime, no dependencies
• Cross-platform compilation — one codebase, four targets (linux/darwin × amd64/arm64)
• Low resource usage — less than 10MB binary, ~15MB RAM at runtime
• Concurrency model — goroutines for parallel service discovery

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Node Agent  │────▶│  API (Go)    │────▶│  PostgreSQL  │
│  (per VPS)   │     │  + Gin       │     │  + Redis     │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                     ┌──────▼───────┐
                     │  Web Dash    │
                     │  (Next.js)   │
                     └──────────────┘

Service Discovery

The agent discovers services through multiple strategies:

1. systemd — systemctl list-units --type=service for system services
2. Docker — Docker Engine API for container inspection
3. Cgroup walk — /sys/fs/cgroup/user.slice/ to find user-level services
4. Port scanning — active listening ports via /proc/net/tcp

The cgroup approach was a breakthrough — it finds services started by any user on the system, not just root. This caught services running under the openclaw user that systemd queries missed.

What It Collects

Category	Details
System	CPU, RAM, disk, network, uptime, OS
Services	Name, status, uptime (from systemd/cgroup/Docker)
Certificates	SSL expiry, issuer, domains
Packages	Installed packages with versions
Containers	Docker container status, image, ports
Firewall	Active rules (iptables/nftables)
Cloud	Provider detection (Tencent, AWS, GCP, Azure, Hetzner, DO)

Deployment

One-liner install:

curl -sfL https://nodestral.web.id/install.sh | sh -s <install-token>

CI/CD via GitHub Actions — PRs trigger build only, git tags trigger build + deploy. Cross-platform releases as GitHub assets.

What’s Next

• Auto-update mechanism for the agent
• MCP gateway (node-mcp) for AI-driven infrastructure management
• Install script refactor for user-space default installation

---

Nodestral is open source at github.com/nodestral. Live at nodestral.io.