Listen to this Post
Introduction:
Traditional monitoring stacks like Grafana paired with Prometheus are powerful but demand significant configuration effort and system resources, often becoming a project in themselves. Beszel emerges as a lightweight alternative that rethinks server and container observability with a security-by-design architecture. Developed in Go, it employs a streamlined hub-and-agent model with modern encryption (Curve25519, ChaCha20-Poly1305) and Ed25519 key authentication, delivering enterprise-grade monitoring with minimal operational overhead.
Learning Objectives:
- Understand the architectural benefits of a lightweight, Go-based monitoring system compared to traditional heavy stacks.
- Master the deployment of Beszel’s hub-and-agent components using both binary and Docker methods, including secure communication setup.
- Implement proactive security alerts, integrate OAuth/OIDC authentication, and automate backups for a resilient monitoring infrastructure.
You Should Know:
- Decoding the Beszel Architecture: Hub, Agent, and Fortified Communications
Beszel operates on a two-component model: the Hub and the Agent.
The Hub is the central web dashboard, built on PocketBase with an integrated SQLite database. It handles multi-user management, alert configuration, and data visualization. The Agent is the lightweight process installed on each monitored system. It does not require a public IP, as it connects outbound to the Hub, which is a significant security advantage for monitoring internal resources behind NAT.
From a security operations perspective, the agent does not open a traditional port for listening. Instead, it embeds a minimal SSH server that communicates exclusively outbound. The communication channel is secured with Ed25519 keys for authentication and the Curve25519 and ChaCha20-Poly1305 cipher suites for data in transit, which are among the most modern and secure cryptographic standards available. Furthermore, interactive terminal allocation is disabled at the code level, drastically reducing the attack surface that could be exploited by an attacker who compromises the communication channel.
Step‑by‑step guide to installing the Beszel Hub using the binary method:
1. Download and Execute: Run the official installation script, which installs the binary and creates a systemd service.
curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-hub.sh -o install-hub.sh && chmod +x install-hub.sh && sudo ./install-hub.sh
2. Verify Service: Ensure the service is active.
sudo systemctl status beszel-hub
3. Access Dashboard: Open a web browser and navigate to `http://
2. Deploying with Docker Compose: The Complete Stack
For those who prefer containerized environments, Beszel integrates seamlessly with Docker. The following `docker-compose.yml` is a production-ready configuration that runs both the Hub and an Agent on the same machine.
Step‑by‑step guide:
1. Create a `docker-compose.yml` file:
name: beszel services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data - ./beszel_socket:/beszel_socket beszel-agent: image: "henrygd/beszel-agent:latest" container_name: "beszel-agent" restart: unless-stopped network_mode: host volumes: - ./beszel_socket:/beszel_socket - /var/run/docker.sock:/var/run/docker.sock:ro environment: LISTEN: /beszel_socket/beszel.sock KEY: "ssh-ed25519 <YOUR_PUBLIC_KEY>"
2. Deploy the stack:
docker-compose up -d
3. This configuration uses a Unix socket for inter-container communication, bypassing network layers for enhanced performance. The agent mounts the Docker socket (docker.sock) to collect real-time metrics for each container, providing granular visibility into resource consumption per service.
3. Strengthening Authentication with OAuth2 and OIDC
In line with zero-trust principles, Beszel supports OAuth2 and OpenID Connect (OIDC) to integrate with existing identity providers like Google, GitHub, GitLab, Keycloak, and others.
Step‑by‑step guide to configuring OAuth:
- Log into the Beszel Hub as an administrator.
- Navigate to the PocketBase Admin UI (usually
http://<HUB_IP>:8090/_/). - Under “Settings,” locate the “Auth providers” section and configure your chosen OAuth provider with your application’s Client ID and Secret.
- To enforce OAuth-only access and disable local password authentication, set the following environment variable on the Hub container or service:
DISABLE_PASSWORD_AUTH=true. This forces all users to authenticate via your corporate SSO or chosen identity provider, centralizing access control and simplifying user lifecycle management.
4. Configuring Intelligent Alerts with Shoutrrr
Beszel uses the Shoutrrr library to send customizable alerts to a wide range of platforms, including Discord, Telegram, Slack, Microsoft Teams, and email. This allows real-time notifications for critical events such as high CPU load, memory exhaustion, disk failures, or unexpected container restarts.
Step‑by‑step guide:
- In the Beszel Hub dashboard, click on the system you want to monitor.
2. Navigate to the Alerts tab.
- Click Add alert, define a threshold (e.g.,
CPU usage > 85% for 5 minutes), and set a check interval. - For the Notification URL, provide the Shoutrrr-compatible endpoint for your service. For example:
`discord://webhook_id/webhook_token`
`telegram://bot_token@telegram?channels=chat_id`
`smtp://username:password@host:25/?fromAddress=from&toAddresses=to`
- Test the configuration to ensure alerts are delivered as expected. A well-structured alerting policy turns raw telemetry into actionable intelligence, enabling a proactive security posture.
5. Automating Backups with S3-Compatible Storage
Data persistence is critical for any monitoring solution. Beszel supports automatic, scheduled backups to either local disk or any S3-compatible object storage (e.g., AWS S3, MinIO, or Backblaze B2).
Step‑by‑step guide for S3 backups:
- In the Hub dashboard, go to Settings > Backups.
2. Enable S3-Compatible Storage.
- Fill in your endpoint, bucket name, access key ID, and secret access key.
- Define a backup schedule (e.g., daily at 02:00 UTC).
- Save the configuration. The hub will now automatically and seamlessly push encrypted backups to your remote storage, providing a robust disaster recovery solution.
6. Monitoring Windows and Linux Servers
Beszel is cross-platform and can monitor Linux and Windows environments. For Windows, a dedicated agent binary is available.
Step‑by‑step guide for adding a Windows server:
1. In the Beszel Hub, click Add System.
- Enter a name and the IP address of the Windows server.
3. Select the Binary tab.
- Copy the one-liner command provided (e.g.,
beszel-agent --key <KEY> --port 45876). - On the Windows server, download the agent from the GitHub releases page, open a command prompt as Administrator, and run the command. This will start the agent and establish a secure, outbound connection to the Hub, allowing you to monitor CPU, memory, disk, network, and even GPU usage on the Windows system.
What Undercode Say:
Key Takeaway 1: Beszel delivers a “90% solution” by providing the most critical monitoring metrics (CPU, RAM, Disk, Docker) with zero dashboard configuration, freeing up valuable engineering time.
Key Takeaway 2: The security model is its standout feature; by using an outbound-only SSH connection with state-of-the-art cryptography (Curve25519, Ed25519) and disabling interactive shells, it inverts the traditional, high-risk monitoring architecture.
- Analysis: Beszel doesn’t aim to compete with the infinite customizability of Grafana, but rather solves a different problem: providing a lightweight, secure, and instantly usable observability layer. This is ideal for small to medium-sized production environments, homelabs, and edge computing scenarios where resource overhead is a premium. Its use of Go ensures it remains performant and cross-platform. The open-source community has already embraced it, as evidenced by its rapid growth and active discussions on GitHub. The tool’s trajectory suggests it is poised to become the default choice for developers and sysadmins who prioritize simplicity and security over complexity and feature bloat.
Prediction:
- -1 Beszel’s very simplicity may become a limitation for large enterprises requiring complex, multi-dimensional data correlation and advanced analytics, preventing it from fully displacing platforms like Datadog or Dynatrace in those specific niches.
- +1 The rising costs and complexities of commercial SaaS monitoring tools are driving a major shift toward lightweight, open-source alternatives like Beszel, which is positioned to experience significant adoption in the self-hosted and edge computing markets over the next 18 months.
- +1 Beszel’s architectural model—a static, outbound-only binary collecting metrics—is inherently more defensible against network-based attacks than traditional agents that listen on open ports, making it a compelling choice for security-conscious teams adopting Zero Trust principles.
▶️ Related Video (86% Match):
🎯Let’s Practice For Free:
🎓 Live Courses & Certifications:
Join Undercode Academy for Verified Certifications
🚀 Request a Custom Project:
Secure, high-velocity infrastructure and disruptive technological engineering. Contact our engineering team for high-tier development and proprietary systems:
[email protected]
💎 Smart Architecture | 🛡️ Secure by Design | ⭐ Trusted by Thousands
IT/Security Reporter URL:
Reported By: Laurent Minne – Hackers Feeds
Extra Hub: Undercode MoN
Basic Verification: Pass ✅
