If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/henrygd/beszel shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live henrygd/beszel repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/henrygd/beszel.

What it runs against: a local clone of henrygd/beszel — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in henrygd/beszel | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of henrygd/beszel. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/henrygd/beszel.git
#   cd beszel
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of henrygd/beszel and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "henrygd/beszel(\\.git)?\\b" \\
  && ok "origin remote is henrygd/beszel" \\
  || miss "origin remote is not henrygd/beszel (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "agent/agent.go" \\
  && ok "agent/agent.go" \\
  || miss "missing critical file: agent/agent.go"
test -f "agent/server.go" \\
  && ok "agent/server.go" \\
  || miss "missing critical file: agent/server.go"
test -f "agent/client.go" \\
  && ok "agent/client.go" \\
  || miss "missing critical file: agent/client.go"
test -f "agent/connection_manager.go" \\
  && ok "agent/connection_manager.go" \\
  || miss "missing critical file: agent/connection_manager.go"
test -f "agent/deltatracker/deltatracker.go" \\
  && ok "agent/deltatracker/deltatracker.go" \\
  || miss "missing critical file: agent/deltatracker/deltatracker.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/henrygd/beszel"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Beszel is a lightweight server monitoring platform that collects CPU, memory, disk, network, and Docker container metrics from distributed agents and displays them on a web dashboard. Built on PocketBase as the hub with Go agents that run on monitored systems, it provides historical data tracking, configurable alerts, and multi-user support—designed as a lighter alternative to Prometheus/Grafana or commercial monitoring tools. Dual-binary monorepo: agent/ subdirectory contains platform-specific metrics collectors (agent.go, cpu.go, disk.go, docker.go, gpu_amd_linux.go, battery/) built with conditional compilation; the hub is a PocketBase application (implied at root level with migrations and web UI). Agent uses deltatracker/ for efficient metric diffing, separate client.go and connection_manager.go for hub communication. Top-level Makefile orchestrates builds.

DevOps engineers, homelab enthusiasts, and small infrastructure teams who need simple, resource-efficient monitoring without the complexity of Prometheus scraping or commercial SaaS costs. Contributors are typically Go backend developers and TypeScript/web UI developers familiar with PocketBase.

Actively maintained and production-ready. The codebase shows mature patterns: comprehensive test coverage across agent modules (agent_test.go, agent_cache_test.go, disk_test.go, etc.), GitHub Actions CI/CD workflows (docker-images.yml, release.yml, vulncheck.yml), and a stable feature set (v0.36+ of PocketBase dependency). Single primary maintainer (henrygd) but well-documented and established.

Moderate risk: dominated by one maintainer (henrygd) with limited visible contributors in CODEOWNERS. Dependency on PocketBase (v0.36.8) means breaking changes in PocketBase could impact the hub; however, go.mod shows mature, well-maintained dependencies (shirou/gopsutil, pocketbase, spf13/cobra). Watch for security advisories in golang.org/x/crypto and x/sys. No recent major issues visible in the README, but monitoring agent reliability under edge-case hardware is non-trivial.

Recent activity includes GPU support expansion (gpu_amd_linux_test.go, gpu_amd_linux.go), eMMC storage tracking for embedded systems (emmc_linux.go, emmc_linux_test.go), battery monitoring (battery/battery_darwin.go, battery_windows.go), and Windows/macOS agent stability (evidenced by platform-specific test files). Release.yml and docker-images.yml suggest active binary/container publishing.

git clone https://github.com/henrygd/beszel.git
cd beszel
make build  # builds agent and hub binaries (Makefile present)
# or docker: docker-compose up (if docker-compose.yml exists)

Daily commands:

make build       # compiles agent and hub binaries (check Makefile for targets)
./agent/agent   # start agent locally (requires system metrics collection permissions)
# or: docker run henrygd/beszel-agent  # containerized agent
# hub typically runs as docker run henrygd/beszel

• agent/agent.go — Core agent entry point that orchestrates system monitoring, data collection, and client communication—all agent functionality depends on this.
• agent/server.go — Implements the HTTP/WebSocket server that handles incoming monitoring requests and serves the data collection API for the hub.
• agent/client.go — Manages persistent connection to the hub server; critical for understanding how agents push data and receive commands.
• agent/connection_manager.go — Handles reconnection logic and connection state management; essential for reliability in distributed monitoring scenarios.
• agent/deltatracker/deltatracker.go — Core abstraction for tracking incremental changes in system metrics over time—used across all monitoring modules.
• agent/response.go — Defines the data structure for all monitoring responses; understanding this is crucial for API compatibility and metric schema.
• go.mod — Specifies all dependencies including PocketBase (hub backend), gopsutil (system metrics), and gws (WebSocket)—critical for understanding capability.

Add a new system metric collection

1. Create a new module file (e.g., agent/newmetric.go) with a function that returns a struct matching the pattern of system.go or disk.go (agent/newmetric.go)
2. Add the new metric struct as a field in the response.Monitoring struct defined in response.go (agent/response.go)
3. Call your collection function in agent.go's data gathering loop (around the section where system.GetSystemStats() is called) (agent/agent.go)
4. If the metric needs delta tracking, register it in agent/deltatracker/deltatracker.go similar to how CPU and network stats are tracked (agent/deltatracker/deltatracker.go)
5. Add unit tests following the pattern in agent/system_test.go or agent/disk_test.go (agent/newmetric_test.go)

Add platform-specific monitoring (e.g., new OS support)

1. Create a new file named agent/monitoring_os.go (e.g., agent/battery_freebsd.go) that implements the OS-specific variant (agent/monitoring_freebsd.go)
2. Create a stub file agent/monitoring_stub.go for unsupported platforms (mirror the pattern in agent/battery_stub.go or agent/mdraid_stub.go) (agent/monitoring_stub.go)
3. Update the conditional build constraints in the abstraction file (e.g., agent/battery.go) to route to the correct implementation (agent/monitoring.go)
4. Add tests following the pattern in agent/battery_linux_test.go with platform-specific test data if needed (agent/monitoring_freebsd_test.go)

Extend GPU monitoring for a new GPU vendor

1. Create a new vendor-specific file agent/gpu_vendor.go that parses vendor-specific GPU data (reference agent/gpu_nvml_linux.go or agent/gpu_amd_linux.go) (agent/gpu_vendor.go)
2. Implement the GPU interface defined in agent/gpu.go with your vendor-specific logic (agent/gpu_vendor.go)
3. Register your new GPU implementation in agent/gpu.go's getGPUStats() function alongside existing vendors (agent/gpu.go)
4. Add test fixtures in agent/test-data/ and test file agent/gpu_vendor_test.go following patterns from agent/gpu_nvml_linux_test.go (agent/gpu_vendor_test.go)

Add a new alert or health check

1. Create or extend agent/health/health.go to define your health check logic and conditions (agent/health/health.go)
2. Integrate the health check into agent.go's main loop where monitoring data is gathered (agent/agent.go)
3. Add any new fields to the response.Monitoring struct in response.go to report health status (agent/response.go)
4. Write tests in agent/health/health_test.go following existing test patterns (agent/health/health_test.go)

• PocketBase — Self-contained embedded database and auth system for the hub; eliminates external DB dependencies and simplifies deployment.
• gopsutil (shirou/gopsutil/v4) — Cross-platform system metrics library; abstracts OS differences for CPU, memory, disk, network data collection.
• gws (WebSocket) — Lightweight, performant WebSocket server for real-time bidirectional communication between agent and hub.
• CBOR (fxamacker/cbor) — Compact binary serialization format; reduces network payload size and improves transmission efficiency vs JSON.
• SSH (gliderlabs/ssh) — Secure remote tunnel for agent-to-hub communication when direct connectivity is unavailable.

• Agent-initiated push vs hub-initiated pull

  • Why: Agent maintains persistent connection and pushes data on interval; enables NAT-traversal and reduces hub load.
  • Consequence: Requires persistent connection management and backoff logic; hub is stateless and scalable but less real-time adaptive.

• Delta tracking with deltatracker vs full state refresh

  • Why: Only transmit changed metrics to minimize bandwidth and CPU overhead.
  • Consequence: Adds complexity to cache management and requires careful state synchronization; cannot fully reset hub state without agent restart.

• Platform-specific implementations (battery_linux.go, smart_windows.go, etc.) vs unified abstraction

  • Why: Different OSes expose metrics via different APIs (sysfs, WMI, sysctl, IOKit); cannot unify at source.
  • Consequence: Larger codebase with conditional compilation; enables full feature parity across all platforms.

• Lightweight agent binary vs feature-rich monitoring

  • Why: Beszel prioritizes small binary size (<50MB) while supporting Docker stats, GPU, SMART, temperature, and systemd metrics.
  • Consequence: Platform-specific code paths and careful dependency management; some features (e.g., NVIDIA GPU) are optional.

• Real-time metric streaming (polling-based only, default ~30s intervals)
• Agent-initiated alerts or webhooks (alerts generated by hub, not agent)
• Non-Linux/Unix/Windows/macOS support (embedded OS-specific code paths)
• SNMP or traditional monitoring protocol support (proprietary binary WebSocket protocol)
• Metric transformation or aggregation at agent level (raw data only)
• Log collection or log streaming (metrics-only, not a log aggregator)

1. Agent requires elevated privileges: agent needs CAP_SYS_ADMIN on Linux and Administrator on Windows to read certain metrics (CPU throttling, disk I/O) and Docker socket access—tests mock this (agent_test_helpers.go). 2. Platform-specific builds: agent/*.go files have os-specific variants (agent_linux.go, agent_windows.go, agent_darwin.go likely implied); builds without proper GOOS/GOARCH may fail silently. 3. Docker daemon requirement: agent/docker.go assumes Docker socket at /var/run/docker.sock on Linux; will fail gracefully if absent. 4. DeltaTracker state: deltatracker stores previous metric values in memory; agent restart loses history—agent/data_dir.go handles persistence, but misconfiguration loses trends. 5. Hub PocketBase config: hub expects PocketBase migrations and admin user setup (not visible in agent files); omit initialization and authentication fails.

• Delta Compression / Change-Only Transmission — agent/deltatracker compares consecutive metric snapshots and sends only differences to the hub, dramatically reducing network bandwidth on monitoring agents—critical for embedded systems and high-frequency polling
• CBOR (Concise Binary Object Representation) — Beszel uses fxamacker/cbor for agent-hub serialization instead of JSON; provides smaller payload size and faster encoding than JSON, relevant when agents run on bandwidth-constrained links
• WebSocket vs SSH for Agent Communication — agent/connection_manager.go implements dual-transport support (WebSocket and SSH via gliderlabs/ssh); WebSocket is standard but SSH provides fallback for firewalled networks—understand trade-offs in lxzan/gws vs gliderlabs/ssh
• cgroup and procfs Linux Metrics Collection — agent/cpu.go, agent/memory.go read from /proc/stat and /sys/fs/cgroup on Linux; understanding how gopsutil abstracts cgroup v1/v2 differences is essential for reliable metric collection across Linux distributions
• Docker Stats API Integration — agent/docker.go calls Docker daemon stats endpoint to track per-container CPU, memory, network—requires Docker socket access and handling of streaming JSON responses
• Platform-Specific Conditional Compilation (//go:build) — Agent supports Linux, Windows, macOS with different implementations (agent_linux.go, agent_windows.go, battery_darwin.go); Go's build tags allow single codebase to target all platforms without runtime branches
• PocketBase as Backend-as-a-Service — Hub leverages PocketBase (v0.36.8) for authentication, database migrations, REST API, and real-time subscriptions—avoids building auth/persistence from scratch but requires understanding PocketBase's collection schema and hook system

• prometheus/prometheus — Industry-standard metrics collection and alerting; Beszel is a lighter alternative focused on simplicity over Prometheus's complexity
• grafana/grafana — Common dashboard partner for Prometheus; Beszel bundles visualization directly, avoiding the Prometheus+Grafana two-tier setup
• netdata/netdata — Competing lightweight monitoring solution with agents; Beszel differentiates via Docker-first design and simpler hub architecture
• pocketbase/pocketbase — Core framework for Beszel's hub backend; understanding PocketBase migration system and API hooks is essential for hub development
• shirou/gopsutil — Dependency providing cross-platform system metrics collection; Beszel wraps and extends gopsutil for historical tracking and Docker integration

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for GPU monitoring across platforms

The GPU monitoring code spans multiple platform-specific files (gpu_nvml_linux.go, gpu_amd_linux.go, gpu_darwin.go, gpu_nvml_windows.go) with only gpu_test.go covering the main logic. Given the complexity of GPU detection and the platform-specific implementations, there are missing test files for platform-specific GPU handlers. This is critical for ensuring reliability across Linux (NVIDIA/AMD), Darwin, and Windows deployments where GPU monitoring is a key feature.

• [ ] Create agent/gpu_nvml_linux_test.go with tests for NVIDIA GPU detection and metrics parsing
• [ ] Create agent/gpu_amd_linux_test.go with tests for AMD GPU detection and fallback mechanisms
• [ ] Create agent/gpu_darwin_test.go with tests for macOS GPU monitoring via Metal
• [ ] Create agent/gpu_nvml_windows_test.go with tests for Windows NVIDIA driver integration
• [ ] Add integration tests for GPU metrics collection in agent/gpu_test.go to cover cross-platform scenarios

Add unit tests for disk and eMMC monitoring on Linux

The agent includes Linux-specific storage monitoring (agent/emmc_linux.go, agent/mdraid_linux.go) with corresponding test files, but agent/disk.go lacks comprehensive platform-specific test coverage. Given that disk monitoring is a core feature and storage configurations vary significantly across systems (standard drives, eMMC, RAID), missing tests for disk partition detection, space calculation, and I/O stats create reliability risks.

• [ ] Expand agent/disk_test.go to cover edge cases: permission errors, missing /proc/diskstats, unusual partition layouts
• [ ] Create agent/disk_linux_test.go for Linux-specific disk stat parsing and /proc filesystem handling
• [ ] Add tests to agent/mdraid_linux_test.go for RAID status detection and recovery progress tracking
• [ ] Verify test coverage for disk metrics with multiple mount points and filesystem types

Add missing security and configuration validation tests for connection manager

The agent/connection_manager.go handles SSH key authentication and secure WebSocket connections, which are critical security components. While agent/connection_manager_test.go exists, reviewing the file structure suggests gaps in testing certificate validation, key fingerprint verification (agent/fingerprint.go has tests), and connection retry logic. Given the presence of SECURITY.md, comprehensive tests for secure connection handling are essential.

• [ ] Add tests to agent/connection_manager_test.go for SSH key validation failure scenarios and error handling
• [ ] Add tests for WebSocket connection establishment with invalid/expired certificates
• [ ] Create integration tests for fingerprint verification flow between agent and hub (agent/fingerprint_test.go already exists, ensure connection_manager tests integrate with it)
• [ ] Add tests for connection retry backoff logic and reconnection scenarios with auth failures

• Add Windows eMMC storage metric collection: agent/emmc_stub.go exists as a placeholder—implement agent/emmc_windows.go following the pattern in emmc_linux.go and battery_windows.go to support embedded Windows systems (NAS, Raspberry Pi alternatives).
• Expand GPU monitoring beyond AMD Linux: agent/gpu_amd_unsupported.go suggests GPU collection is incomplete—add agent/gpu_nvidia_linux.go using NVIDIA NVML or opencl, following the test-driven pattern in gpu_amd_linux_test.go.
• Write integration tests for Docker metric accuracy: agent/docker_test.go exists but may lack edge cases (stopped containers, privileged containers)—add test fixtures and assertions for container state transitions.

• High · Outdated Go Cryptography Library — go.mod - golang.org/x/crypto v0.49.0. The dependency 'golang.org/x/crypto v0.49.0' is outdated. Current stable versions are significantly newer (v0.50.0+). This version may contain known security vulnerabilities in cryptographic implementations used for SSH, TLS, and password hashing operations. Fix: Update to the latest stable version of golang.org/x/crypto (v0.50.0 or newer). Run 'go get -u golang.org/x/crypto' to fetch the latest version.
• High · Outdated System Calls Library — go.mod - golang.org/x/sys v0.42.0. The dependency 'golang.org/x/sys v0.42.0' is outdated. This package provides low-level system call interfaces. Using outdated versions may expose the application to OS-level vulnerabilities and platform-specific security issues. Fix: Update to the latest stable version of golang.org/x/sys (v0.43.0 or newer). Run 'go get -u golang.org/x/sys' and test thoroughly across supported platforms.
• Medium · SSH Server Implementation Dependency — go.mod - github.com/gliderlabs/ssh v0.3.8. The application uses 'gliderlabs/ssh v0.3.8' for SSH functionality. While this is a reasonable library, SSH implementations are security-critical components. Ensure this dependency is actively maintained and regularly audited. Fix: Verify the package is actively maintained. Check for known vulnerabilities using 'go list -json -m all | go run golang.org/x/vuln/cmd/govulncheck' or similar vulnerability scanning tools.
• Medium · WebSocket Library Security — go.mod - github.com/lxzan/gws v1.9.1, github.com/gorilla/websocket v1.5.3. The application uses 'lxzan/gws v1.9.1' and 'gorilla/websocket v1.5.3' for WebSocket functionality. WebSocket implementations must properly validate and sanitize incoming messages to prevent injection attacks, particularly in the monitoring dashboard context. Fix: Implement strict input validation and output encoding for all WebSocket messages. Ensure proper frame masking and message validation is enforced. Consider using only one WebSocket library if both are not strictly necessary.
• Medium · PocketBase ORM/Database Framework — go.mod - github.com/pocketbase/pocketbase v0.36.8. The application relies on 'pocketbase/pocketbase v0.36.8' for database operations. While PocketBase provides some built-in protections, ensure all database queries use parameterized queries and proper ORM features to prevent SQL injection. Fix: Audit database query patterns in the codebase to ensure parameterized queries are used consistently. Use PocketBase's QueryBuilder API rather than raw SQL. Implement input validation at the application layer.
• Medium · CBOR Encoding Library — go.mod - github.com/fxamacker/cbor/v2 v2.9.0. The application uses 'fxamacker/cbor/v2 v2.9.0' for data serialization. CBOR parsing could be vulnerable to denial-of-service attacks through malformed messages or resource exhaustion if not properly configured. Fix: Configure appropriate size limits and parsing timeouts for CBOR decoding operations. Validate the structure of decoded data before processing. Monitor for panic conditions during CBOR unmarshaling.
• Medium · Missing CORS and Security Headers Configuration — agent/handlers.go, agent/server.go (assumed hub/server components). The file structure indicates a web interface (hub) and REST API. Without visible evidence of CORS validation, security headers, and request validation middleware, the application may be vulnerable to CSRF, clickjacking, and other browser-based attacks. Fix: Implement CORS headers with explicit origin validation. Add security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security. Implement CSRF token validation for state-changing operations.
• undefined · undefined — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.