Beszel/README.md

Beszel - Unified Monitoring Platform

Lightweight server monitoring, website monitoring, and domain expiry tracking in a single dashboard.

Beszel is a unified monitoring platform that combines system metrics, service uptime monitoring, and domain/SSL expiry tracking. Built on PocketBase with a modern React frontend, it is designed to be lightweight, self-hosted, and production-ready.

Quick Start

Docker Compose

# Clone the repository
git clone https://github.com/henrygd/beszel.git
cd beszel

# Copy and edit environment variables (optional)
cp .env.example .env

# Start the hub
make start
# or: docker compose up -d

# View logs
make logs

# Stop everything
make stop

The hub will be available at http://localhost:8090. Create your admin account on first visit.

Agents run on separate hosts and connect to the hub. See Adding Agents below.

Environment Variables

Variable	Default	Description
APP_URL	http://localhost:8090	Public URL for links
INSTANCE_NAME	Beszel Monitoring	Instance display name
REGISTRATION_ENABLED	true	Allow new user registration
MAX_MONITORS_PER_USER	50	Monitor limit per user
MAX_DOMAINS_PER_USER	50	Domain limit per user
MAX_STATUS_PAGES	10	Status page limit
TWO_FACTOR_ENABLED	true	Enable 2FA
PASSKEY_ENABLED	true	Enable passkey auth
STATUS_PAGES_ENABLED	true	Enable public status pages
BADGES_ENABLED	true	Enable SVG badge generation
PAGESPEED_ENABLED	true	Enable PageSpeed checks
SUBDOMAIN_DISCOVERY	true	Auto-discover subdomains

Features

System Monitoring

• CPU, memory, disk, network metrics with historical charts
• Docker / Podman container stats
• GPU monitoring (Nvidia, AMD, Intel)
• Temperature sensors and battery status
• S.M.A.R.T. disk health tracking

Website & Service Monitoring

• HTTP/HTTPS, TCP, Ping, DNS checks
• Keyword and JSON query validation
• Response time tracking with Recharts visualizations
• Uptime statistics (24h / 7d / 30d)
• Maintenance windows with alert suppression

Domain Monitoring

• WHOIS lookup with RDAP + TCP fallback (works in scratch containers)
• SSL certificate expiry tracking
• DNS records (NS, MX, TXT)
• Subdomain auto-discovery (50 common subdomains)
• Registrar, host geolocation, and IP info
• Bulk CSV import / JSON export

Platform

• Multi-user with role-based access
• OAuth 2.0 / OIDC support
• Public status pages with custom CSS
• Incident management with acknowledge/resolve workflow
• Calendar view for expiry dates and incidents
• Prometheus metrics export (/metrics)
• SVG status badges for embedding
• Browser push notifications + PWA support
• PageSpeed Insights / Lighthouse integration
• Automatic backups to disk or S3

Architecture

Hub (Go + PocketBase + React)
- Web UI (port 8090)
- REST API + WebSocket
- SQLite database with migrations
- Scheduled jobs (domain checks, heartbeat cleanup)

Agent (Go)
- Runs on monitored hosts
- Collects system + Docker metrics
- Connects to hub via SSH tunnel

Adding Agents

Agents run on the hosts you want to monitor and connect back to the hub via SSH.

On a remote host

# Build the agent binary
make build-agent

# Copy the binary to the remote host
# Set KEY to the public key from the hub UI (Settings > Add System)
KEY="ssh-ed25519 ..." ./beszel-agent

With Docker on a remote host

# Build the agent image
make docker-agent

# Run the agent container
docker run -d \
  --name beszel-agent \
  --pid host \
  -e KEY="ssh-ed25519 ..." \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -p 45876:45876 \
  beszel-agent:latest

Building

# Build hub + agent binaries
make build

# Build with Docker
make docker-hub
make docker-agent

# Development mode
make dev

API

Protected endpoints require Bearer token authentication.

Endpoint	Description
GET /api/beszel/monitors	List monitors
GET /api/beszel/domains	List domains
GET /api/beszel/status-pages	List status pages
GET /api/beszel/incidents	List incidents
GET /api/beszel/maintenance	List maintenance windows
GET /metrics	Prometheus metrics (public)
GET /status/:slug	Public status page
GET /badge/:type/:id.svg	Status badge (public)

Credits

Based on Beszel by henrygd.

License

MIT License. See LICENSE.