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.

Features

• 🖥️ Multi-platform Support - Deploy agents on Linux, macOS, and Windows (AMD64 & ARM64)
• 📈 Real-time Monitoring - Track CPU, RAM, and Disk usage with 15-second refresh 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 auto-refresh
• 🚀 Minimal Dependencies - Only Chi router and Templ templating engine (plus Go stdlib)
• ⚙️ Auto-Generation - Agent IDs automatically generated from hostname
• 💾 In-Memory Storage - Fast, zero-database setup (perfect for small to medium deployments)

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

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 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

Agent Detail Page

Click any agent hostname to see detailed statistics:

• Large CPU usage display with progress bar
• Memory and disk breakdowns
• Agent ID and detailed metadata
• Last exact timestamp
• Delete button for removing the agent

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)
• API Endpoints:
  • POST /api/report - Agent stats reporting
  • GET /api/agents - List all agents
  • GET /api/agents/{id} - Get specific agent stats

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
• Responsive Design: Works on desktop, tablet, and mobile
• Auto-Refresh: Dashboard refreshes every 5 seconds
• Color-coded Status: Visual indicators for system health

Project Structure

nerd-monitor/
├── cmd/
│   ├── agent/
│   │   └── main.go           # Agent executable
│   └── server/
│       └── main.go           # Server executable
├── internal/
│   ├── api/
│   │   └── api.go            # API handlers
│   ├── auth/
│   │   ├── middleware.go     # Auth middleware
│   │   └── errors.go         # Error definitions
│   ├── stats/
│   │   └── stats.go          # System stats collection
│   ├── store/
│   │   └── store.go          # In-memory agent storage
│   └── ui/
│       └── handlers.go       # Dashboard handlers
├── views/
│   ├── layout.templ          # Base layout template
│   ├── dashboard.templ       # Dashboard page
│   ├── agent_detail.templ    # Agent detail page
│   ├── login.templ           # Login page
│   ├── components.templ      # Reusable components
│   └── generate.go           # Templ code generation
├── 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)
• Dashboard Refresh: 5 seconds (configurable)
• Agent Reporting: 15 seconds (configurable)

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

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

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

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

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

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

Running Tests

go test ./...

Code Formatting

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

Contributing

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

Future Enhancements

• Database persistence (SQLite/PostgreSQL)
• Alerting system (email/Slack notifications)
• Historical data / graphing
• Agent grouping and tagging
• Custom metric collection
• TLS/HTTPS support
• Multi-tenancy
• API documentation (Swagger)

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