Beszel Self-Hosted with Docker

This repository provides a Docker Compose stack for running a self-hosted Beszel hub together with its agent. Beszel gives you a clean, real-time view of host metrics, Docker containers, and service uptime without depending on any third-party SaaS.

Features

• Works out of the box: Set a couple of secrets in .env and start the stack.
• Hub + Agent included: Ships both the Beszel UI/API service and the monitoring agent so you immediately get host metrics.
• Persistent data: Volume mounts keep Beszel configuration, history, and agent state under ./data.
• Host insights: The agent runs in host network mode and has read-only access to the Docker socket to collect resource metrics for containers and the host.
• Shared network ready: The hub attaches to the shared_network bridge, making it easy to expose or monitor other self-hosted services on the same network.
• Helper scripts: restart-docker.sh and update-docker.sh streamline common maintenance tasks.

Getting Started

1. Clone the repository

   git clone https://github.com/AiratTop/beszel-self-hosted
   cd beszel-self-hosted

2. Create the shared Docker network (one-time)

   docker network create shared_network

3. Configure the environment Create a .env file in the project root and set the variables listed below. You can use my Open Source password generator to create a strong password.

4. Start Beszel

   docker compose up -d

5. Open the dashboard Visit http://<your-host>:8090 in a browser, create an admin user, and add the token/key you configured when pairing agents.

Environment variables

The compose file reads two secrets for the agent:

TOKEN=super-secret-agent-token
KEY=change-me-to-a-long-random-string

• TOKEN must match the token you generate inside the Beszel UI under Settings → Agents.
• KEY is the SSH-like private key that Beszel generates alongside the token in the same UI. Always copy both values when you add a new agent.
• If the hub is not running on the same host as the agent, adjust HUB_URL in docker-compose.yml accordingly.

Store the .env file securely and do not commit it to version control.

Usage

• Start: docker compose up -d
• Restart: ./restart-docker.sh
• Update: ./update-docker.sh (pulls the latest images and restarts the containers)
• Logs: docker compose logs -f beszel or docker compose logs -f beszel-agent

Data & backups

All persistent data lives inside the ./data directory:

• ./data/beszel_data – Beszel hub configuration and history
• ./data/beszel_socket – Unix socket shared between hub and agent
• ./data/beszel_agent_data – Local cache/state for the agent

Back up these folders regularly (e.g., with tar or your backup solution of choice) to keep your dashboards and historical metrics safe.

Connecting to other services

The Beszel hub joins the shared_network Docker network. Attach the containers you want to monitor to the same network (or expose them on the host) so Beszel can reach their HTTP endpoints and collect additional checks.

Services

• beszel – The Beszel hub (web UI + API) exposed on port 8090/tcp.
• beszel-agent – Local monitoring agent that forwards host and container metrics to the hub.

See also

• postgresql-self-hosted: A simple and robust PostgreSQL setup.
• mysql-self-hosted: A self-hosted MySQL instance.
• clickhouse-self-hosted: High-performance columnar database for analytics.
• metabase-self-hosted: Self-hosted Metabase on Docker for business intelligence and analytics.
• qdrant-self-hosted: A vector database for AI applications.
• redis-self-hosted: A fast in-memory data store, often used as a cache or message broker.
• caddy-self-hosted: A modern, easy-to-use web server with automatic HTTPS.
• wordpress-self-hosted: Production-ready WordPress stack with MySQL, phpMyAdmin, and WP-CLI.
• n8n-self-hosted: Scalable n8n with workers, Caddy for auto-HTTPS, and backup scripts.
• monitoring-self-hosted: Self-hosted monitoring stack with Prometheus and Grafana.
• ollama-self-hosted: Ready-to-use solution for running Ollama with the Open WebUI on Docker.
• authentik-self-hosted: Authentik is a flexible, open-source Identity & Access Management (IAM) solution.
• gatus-self-hosted: Automated service health dashboard with a PostgreSQL backend and backup scripts.
• beszel-self-hosted: Ready-to-run Beszel hub + agent stack for monitoring your infrastructure.

License

This project is licensed under the MIT License – see the LICENSE file for details.

---

Author

AiratTop

• Website: airat.top
• GitHub: @AiratTop
• Email: mail@airat.top
• Repository: beszel-self-hosted