Nerd Monitor 📊

A lightweight, cross-platform system monitoring solution written in Go. Monitor CPU, memory, and disk usage across multiple machines with a beautiful web dashboard featuring instant real-time updates powered by Server-Sent Events and HTMX.

Features

• 🖥️ Multi-platform Support - Deploy agents on Linux, macOS, and Windows (AMD64 & ARM64)
• ⚡ Instant Real-time Updates - Stats update immediately when agents report, not on fixed intervals
• 🟢 Live Status Indicators - See which machines are online/offline at a glance
• 🔒 Secure Authentication - Session-based admin authentication for the dashboard
• 🧹 Stale Agent Management - Automatically detect and remove agents inactive for 6+ months
• 📱 Responsive Dashboard - Beautiful, modern UI with seamless HTMX-powered updates
• 🚀 Minimal Dependencies - Only Chi router, Templ templating, and HTMX (plus Go stdlib)
• ⚙️ Auto-Generation - Agent IDs automatically generated from hostname
• 💾 In-Memory Storage - Fast, zero-database setup (perfect for small to medium deployments)
• 📡 Server-Sent Events - Real-time push notifications from server to web clients
• 📝 Structured Logging - Comprehensive slog-based logging throughout the application

Quick Start

Prerequisites

• Go 1.23+ (for building)
• Port 8080 available (configurable)

Building

# Build for current OS
make build

# Build for all platforms (Linux, macOS, Windows)
make build-all

# Clean build artifacts
make clean

Binaries are created in the bin/ directory.

Running the Server

# Start with default credentials (admin/admin)
./bin/nerd-monitor-server

# Custom configuration
./bin/nerd-monitor-server \
  -addr 0.0.0.0 \
  -port 8080 \
  -username admin \
  -password securepassword

Then access the dashboard at http://localhost:8080. The interface provides real-time updates - stats refresh instantly when agents report new data!

Running Agents

Linux / macOS

# Connect to local server with default port
./bin/nerd-monitor-agent --server 10.0.20.80

# With custom port
./bin/nerd-monitor-agent --server 10.0.20.80:9090

# With custom reporting interval (default: 15s)
./bin/nerd-monitor-agent --server myserver:8080 --interval 30s

Windows

Use the batch wrapper to run agents as a background process (no visible terminal):

REM Run in background with custom server
nerd-monitor-agent.bat --server 10.0.20.80

REM With custom port
nerd-monitor-agent.bat --server 10.0.20.80:9090 --interval 30s

Dashboard

Overview Page

Shows all connected agents with instant real-time metrics:

• Status Badge - Green (Online) or Red (Offline)
  • Online: Last report within 15 seconds
  • Offline: No report for 15+ seconds
• CPU Usage - Percentage (0-100%)
• Memory Usage - Used / Total with visual progress bar
• Disk Usage - Used / Total with visual progress bar
• Last Seen - Human-readable timestamp
• Live Updates - Stats refresh immediately when agents report new data

Agent Detail Page

Click any agent hostname to see detailed statistics with live updates:

• Large CPU usage display with progress bar (updates in real-time)
• Memory and disk breakdowns
• Agent ID and detailed metadata
• Last exact timestamp
• Delete button for removing the agent
• Instant Updates - CPU stats refresh immediately when agent reports

Stale Agent Management

Agents inactive for 6+ months:

• Display warning banner on dashboard
• Show list of stale agents
• Bulk select and remove functionality
• Keep dashboard clean and organized

Architecture

Server (cmd/server/)

• HTTP Router: Chi v5 for efficient routing
• Authentication: Session-based auth with 24-hour expiry
• Storage: In-memory concurrent-safe store (sync.RWMutex)
• Real-time Broadcasting: Server-Sent Events (SSE) for instant UI updates
• Structured Logging: slog-based logging with debug/info levels
• API Endpoints:
  • POST /api/report - Agent stats reporting (triggers real-time broadcasts)
  • GET /api/agents - List all agents
  • GET /api/agents/{id} - Get specific agent stats
  • GET /api/dashboard/table - HTML fragment for HTMX dashboard updates
  • GET /api/agents/{id}/stats - HTML fragment for HTMX agent detail updates
  • GET /api/events - Server-Sent Events for real-time notifications

Agent (cmd/agent/)

• Stats Collection: Uses gopsutil for cross-platform stats
• Auto-ID Generation: Hostname-based ID generation
• Reporting: Configurable interval (default 15 seconds)
• Resilience: Automatic retry on connection failure
• Graceful Shutdown: Handles SIGTERM and SIGINT

Views (views/)

• Templ Templates: Type-safe HTML templating
• HTMX Integration: Smooth, instant updates without page refreshes
• Server-Sent Events: Real-time push notifications from server
• Responsive Design: Works on desktop, tablet, and mobile
• Color-coded Status: Visual indicators for system health

Project Structure

nerd-monitor/
├── cmd/
│   ├── agent/
│   │   └── main.go           # Agent executable with slog logging
│   └── server/
│       └── main.go           # Server executable with slog logging
├── internal/
│   ├── api/
│   │   └── api.go            # API handlers + real-time broadcaster
│   ├── auth/
│   │   ├── middleware.go     # Auth middleware with detailed logging
│   │   └── errors.go         # Error definitions
│   ├── stats/
│   │   └── stats.go          # System stats collection
│   ├── store/
│   │   └── store.go          # In-memory agent storage with logging
│   └── ui/
│       └── handlers.go       # Dashboard handlers + HTMX endpoints
├── views/
│   ├── layout.templ          # Base layout with HTMX + SSE
│   ├── dashboard.templ       # Dashboard with real-time updates
│   ├── agent_detail.templ    # Agent detail with live stats
│   ├── login.templ           # Login page
│   ├── components.templ      # Reusable components
│   └── *_templ.go            # Generated Templ code
├── Makefile                  # Build system
├── go.mod / go.sum           # Go dependencies
├── AGENTS.md                 # Agent guidelines
├── QUICKSTART.md             # Quick start guide
└── README.md                 # This file

Code Style Guidelines

Following the guidelines in AGENTS.md:

• Imports: Standard library → third-party → internal (alphabetical)
• Formatting: gofmt standards
• Naming: CamelCase for exports, lowercase for unexported
• Error Handling: Explicit checks, contextual wrapping
• Concurrency: sync.RWMutex for shared state, always defer releases
• HTTP: Chi router with proper status codes and Content-Type headers

Configuration

Server Flags

./bin/nerd-monitor-server [OPTIONS]

Options:
  -addr string
      Server address (default "localhost")
  -port string
      Server port (default "8080")
  -username string
      Admin username (default "admin")
  -password string
      Admin password (default "admin")

Agent Flags

./bin/nerd-monitor-agent [OPTIONS]

Options:
  -server string
      Server URL (required)
  -interval duration
      Reporting interval (default 15s)
  -id string
      Agent ID (auto-generated from hostname if empty)

Default Credentials

• Username: admin
• Password: admin

⚠️ Security: Change these credentials in production!

Performance

• Agent Memory: ~8-10 MB (depending on platform)
• Server Memory: Scales with connected agents (~1 MB per 1000 agents)
• Network: Minimal bandwidth (~1 KB per report + SSE connections)
• Real-time Updates: Instant UI updates when agents report stats
• Agent Reporting: 15 seconds (configurable)
• SSE Connections: Lightweight persistent connections for real-time notifications

Building for Specific Platforms

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o bin/nerd-monitor-agent-linux-amd64 ./cmd/agent

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o bin/nerd-monitor-agent-darwin-arm64 ./cmd/agent

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o bin/nerd-monitor-agent-windows-amd64.exe ./cmd/agent

Or use the Makefile:

make build-all

Dependencies

Production

• github.com/go-chi/chi/v5 - HTTP router
• github.com/a-h/templ - HTML templating
• github.com/shirou/gopsutil/v3 - System statistics
• HTMX (CDN) - Frontend interactivity and real-time updates
• Server-Sent Events (Go stdlib) - Real-time push notifications

Go Standard Library

• encoding/json - JSON marshaling
• net/http - HTTP server and client
• sync - Concurrent access (RWMutex)
• time - Timestamps and durations
• os - Hostname, signals, I/O
• crypto/rand - Token generation
• log/slog - Structured logging throughout application

Troubleshooting

Agent not appearing in dashboard

1. Verify server is running: http://localhost:8080
2. Check agent logs for connection errors
3. Ensure correct server address and port
4. Check firewall rules allow outbound connections
5. Check server logs for SSE broadcasting activity

Stats not updating in real-time

1. Verify browser supports Server-Sent Events (SSE)
2. Check browser developer tools for JavaScript errors
3. Ensure /api/events endpoint is accessible (requires authentication)
4. Check server logs for SSE connection/disconnection messages
5. Verify HTMX library loaded correctly

Agent shows "Offline" immediately

1. Check network connectivity between agent and server
2. Verify server address is reachable: ping 10.0.20.80
3. Check if server is listening on the correct port
4. Review server logs for errors
5. Note: Agents are marked offline if no report received in 15 seconds

Can't login to dashboard

1. Verify you're using correct credentials
2. Try the default: admin / admin
3. If changed, restart server with original credentials to reconfigure
4. Check browser cookies are enabled
5. Clear browser cache if SSE connections seem stuck

Windows agent window appears then closes

1. Use nerd-monitor-agent.bat instead of .exe directly
2. The batch wrapper handles background execution
3. Check task manager to verify agent process is running

Development

Regenerating Templates

When modifying .templ files:

make templ
# or
go run github.com/a-h/templ/cmd/templ@latest generate

Viewing Logs

The application uses structured logging with slog. Set log level with:

# Debug logging (shows all activity)
export GOLOGLEVEL=debug

# Info logging (default, shows important events)
export GOLOGLEVEL=info

Running Tests

go test ./...

Code Formatting

gofmt -w ./cmd ./internal ./views

Testing Real-time Features

To test SSE and HTMX functionality:

# Start server
./bin/nerd-monitor-server

# In another terminal, send test stats
curl -X POST "http://localhost:8080/api/report?id=test-agent" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "test", "cpuUsage": 25.5, "ramUsage": 1000000, "ramTotal": 8000000, "diskUsage": 50000000, "diskTotal": 100000000}'

Contributing

Contributions are welcome! Please follow the code style guidelines in AGENTS.md.

Recent Updates

• ✅ Real-time Updates: Instant UI updates via Server-Sent Events and HTMX
• ✅ Structured Logging: Comprehensive slog-based logging throughout
• ✅ Enhanced Monitoring: Better debugging and operational visibility

Future Enhancements

• Database persistence (SQLite/PostgreSQL)
• Alerting system (email/Slack notifications)
• Historical data / graphing with time-series storage
• Agent grouping and tagging
• Custom metric collection
• TLS/HTTPS support
• Multi-tenancy
• API documentation (Swagger/OpenAPI)
• Webhook integrations
• Mobile app companion

License

MIT License - See LICENSE file for details

Support

• Check QUICKSTART.md for common setup issues
• Review AGENTS.md for development guidelines
• Open an issue for bugs or feature requests

---

Made with ❤️ for system administrators and DevOps teams