beszel Documentation

Lightweight server monitoring with historical data, docker stats, and alerts.

24,216 stars Go Go 1 file · ~3,177 tokens #homelab#monitoring#self-hosted
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy beszel on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name beszel -p 8090:8090 --restart always henrygd/beszel:latest
Configured Services & Ports
⚙️ beszel
image: henrygd/beszel:latest
🔌 Ports: 8090:8090
⚙️ beszel-agent
image: henrygd/beszel-agent:latest
docker-compose.yml
yaml (docker-compose.yml) 
# Docs: https://beszel.dev/guide/getting-started
# Env vars: https://beszel.dev/guide/environment-variables

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    environment:
      APP_URL: http://localhost:8090
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket
    # healthcheck:
    #   test: ['CMD', '/beszel', 'health', '--url', 'http://localhost:8090']
    #   interval: 120s
    #   start_period: 10s
    #   timeout: 5s

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - ./beszel_socket:/beszel_socket
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: /beszel_socket/beszel.sock
      HUB_URL: http://localhost:8090
      TOKEN: 
      KEY: ""
    # healthcheck:
    #   test: ['CMD', '/agent', 'health']
    #   interval: 120s

File: README.md

Beszel

Beszel is a lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions.

It has a friendly web interface, simple configuration, and is ready to use out of the box. It supports automatic backup, multi-user, OAuth authentication, and API access.




Features

  • Lightweight: Smaller and less resource-intensive than leading solutions.
  • Simple: Easy setup with little manual configuration required.
  • Docker stats: Tracks CPU, memory, and network usage history for each container.
  • Alerts: Configurable alerts for CPU, memory, disk, bandwidth, temperature, fan speed, load average, and status.
  • Multi-user: Users manage their own systems. Admins can share systems across users.
  • OAuth / OIDC: Supports many OAuth2 providers. Password auth can be disabled.
  • Automatic backups: Save to and restore from disk or S3-compatible storage.

Architecture

Beszel consists of two main components: the hub and the agent.

  • Hub: A web application built on PocketBase that provides a dashboard for viewing and managing connected systems.
  • Agent: Runs on each system you want to monitor and communicates system metrics to the hub.

Getting started

The quick start guide and other documentation is available on our website, beszel.dev. You'll be up and running in a few minutes.

Screenshots

Supported metrics

  • CPU usage - Host system and Docker / Podman containers.
  • Memory usage - Host system and containers. Includes swap and ZFS ARC.
  • Disk usage - Host system. Supports multiple partitions and devices.
  • Disk I/O - Host system. Supports multiple partitions and devices.
  • Network usage - Host system and containers.
  • Load average - Host system.
  • Temperature - Host system sensors.
  • Fan speed - Host system sensors (Linux, via /sys/class/hwmon).
  • GPU usage / power draw - Nvidia, AMD, and Intel.
  • Battery - Host system battery charge.
  • Containers - Status and metrics of all running Docker / Podman containers.
  • S.M.A.R.T. - Host system disk health (includes eMMC wear/EOL and Linux mdraid array health via sysfs when available).

Help and discussion

Please search existing issues and discussions before opening a new one. I try my best to respond, but may not always have time to do so.

Bug reports and feature requests

Bug reports and feature requests can be posted on GitHub issues.

Support and general discussion

Support requests and general discussion can be posted on GitHub discussions or the community-run Matrix room: #beszel:matrix.org.

License

Beszel is licensed under the MIT License. See the LICENSE file for more details.

File: Readme.md

Beszel

Beszel is a lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions.

It has a friendly web interface, simple configuration, and is ready to use out of the box. It supports automatic backup, multi-user, OAuth authentication, and API access.




Features

  • Lightweight: Smaller and less resource-intensive than leading solutions.
  • Simple: Easy setup with little manual configuration required.
  • Docker stats: Tracks CPU, memory, and network usage history for each container.
  • Alerts: Configurable alerts for CPU, memory, disk, bandwidth, temperature, fan speed, load average, and status.
  • Multi-user: Users manage their own systems. Admins can share systems across users.
  • OAuth / OIDC: Supports many OAuth2 providers. Password auth can be disabled.
  • Automatic backups: Save to and restore from disk or S3-compatible storage.

Architecture

Beszel consists of two main components: the hub and the agent.

  • Hub: A web application built on PocketBase that provides a dashboard for viewing and managing connected systems.
  • Agent: Runs on each system you want to monitor and communicates system metrics to the hub.

Getting started

The quick start guide and other documentation is available on our website, beszel.dev. You'll be up and running in a few minutes.

Screenshots

Supported metrics

  • CPU usage - Host system and Docker / Podman containers.
  • Memory usage - Host system and containers. Includes swap and ZFS ARC.
  • Disk usage - Host system. Supports multiple partitions and devices.
  • Disk I/O - Host system. Supports multiple partitions and devices.
  • Network usage - Host system and containers.
  • Load average - Host system.
  • Temperature - Host system sensors.
  • Fan speed - Host system sensors (Linux, via /sys/class/hwmon).
  • GPU usage / power draw - Nvidia, AMD, and Intel.
  • Battery - Host system battery charge.
  • Containers - Status and metrics of all running Docker / Podman containers.
  • S.M.A.R.T. - Host system disk health (includes eMMC wear/EOL and Linux mdraid array health via sysfs when available).

Help and discussion

Please search existing issues and discussions before opening a new one. I try my best to respond, but may not always have time to do so.

Bug reports and feature requests

Bug reports and feature requests can be posted on GitHub issues.

Support and general discussion

Support requests and general discussion can be posted on GitHub discussions or the community-run Matrix room: #beszel:matrix.org.

License

Beszel is licensed under the MIT License. See the LICENSE file for more details.

File: readme.md

Beszel

Beszel is a lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions.

It has a friendly web interface, simple configuration, and is ready to use out of the box. It supports automatic backup, multi-user, OAuth authentication, and API access.




Features

  • Lightweight: Smaller and less resource-intensive than leading solutions.
  • Simple: Easy setup with little manual configuration required.
  • Docker stats: Tracks CPU, memory, and network usage history for each container.
  • Alerts: Configurable alerts for CPU, memory, disk, bandwidth, temperature, fan speed, load average, and status.
  • Multi-user: Users manage their own systems. Admins can share systems across users.
  • OAuth / OIDC: Supports many OAuth2 providers. Password auth can be disabled.
  • Automatic backups: Save to and restore from disk or S3-compatible storage.

Architecture

Beszel consists of two main components: the hub and the agent.

  • Hub: A web application built on PocketBase that provides a dashboard for viewing and managing connected systems.
  • Agent: Runs on each system you want to monitor and communicates system metrics to the hub.

Getting started

The quick start guide and other documentation is available on our website, beszel.dev. You'll be up and running in a few minutes.

Screenshots

Supported metrics

  • CPU usage - Host system and Docker / Podman containers.
  • Memory usage - Host system and containers. Includes swap and ZFS ARC.
  • Disk usage - Host system. Supports multiple partitions and devices.
  • Disk I/O - Host system. Supports multiple partitions and devices.
  • Network usage - Host system and containers.
  • Load average - Host system.
  • Temperature - Host system sensors.
  • Fan speed - Host system sensors (Linux, via /sys/class/hwmon).
  • GPU usage / power draw - Nvidia, AMD, and Intel.
  • Battery - Host system battery charge.
  • Containers - Status and metrics of all running Docker / Podman containers.
  • S.M.A.R.T. - Host system disk health (includes eMMC wear/EOL and Linux mdraid array health via sysfs when available).

Help and discussion

Please search existing issues and discussions before opening a new one. I try my best to respond, but may not always have time to do so.

Bug reports and feature requests

Bug reports and feature requests can be posted on GitHub issues.

Support and general discussion

Support requests and general discussion can be posted on GitHub discussions or the community-run Matrix room: #beszel:matrix.org.

License

Beszel is licensed under the MIT License. See the LICENSE file for more details.

File: supplemental/guides/systemd.md

Installing as a Linux systemd service

This is useful if you want to run the hub or agent in the background continuously, including after a reboot.

There are two scripts, one for the hub and one for the agent. You can run either one, or both.

The install script creates a dedicated user for the service (beszel), downloads the latest release, and installs the service.

If you need to edit the service -- for instance, to change an environment variable -- you can edit the file(s) in /etc/systemd/system/. Then reload the systemd daemon and restart the service.

[!NOTE]
You need system administrator privileges to run the install script. If you encounter a problem, please open an issue.

Hub

Download the script:

bash
curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-hub.sh -o install-hub.sh && chmod +x install-hub.sh

Install

You may specify a port number with the -p flag. The default port is 8090.

bash
./install-hub.sh

Uninstall

bash
./install-hub.sh -u

Update

bash
sudo /opt/beszel/beszel update && sudo systemctl restart beszel-hub

Agent

Download the script:

bash
curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh -o install-agent.sh && chmod +x install-agent.sh

Install

You may optionally include the SSH key and port as arguments. Run ./install-agent.sh -h for more info.

If specifying your key with -k, please make sure to enclose it in quotes.

bash
./install-agent.sh

Uninstall

bash
./install-agent.sh -u

Update

bash
sudo /opt/beszel-agent/beszel-agent update && sudo systemctl restart beszel-agent

Manual install

Hub

  1. Create the system service at /etc/systemd/system/beszel.service
bash
[Unit]
Description=Beszel Hub Service
After=network.target

[Service]
# update the values in the curly braces below (remove the braces)
ExecStart={/path/to/working/directory}/beszel serve
WorkingDirectory={/path/to/working/directory}
User={YOUR_USERNAME}
Restart=always

[Install]
WantedBy=multi-user.target
  1. Start and enable the service to let it run after system boot
bash
sudo systemctl daemon-reload
sudo systemctl enable beszel.service
sudo systemctl start beszel.service

Agent

  1. Create the system service at /etc/systemd/system/beszel-agent.service
bash
[Unit]
Description=Beszel Agent Service
After=network.target

[Service]
# update the values in curly braces below (remove the braces)
Environment="PORT={PASTE_YOUR_PORT_HERE}"
Environment="KEY={PASTE_YOUR_KEY_HERE}"
# Environment="EXTRA_FILESYSTEMS={sdb}"
ExecStart={/path/to/directory}/beszel-agent
User={YOUR_USERNAME}
Restart=always

[Install]
WantedBy=multi-user.target
  1. Start and enable the service to let it run after system boot
bash
sudo systemctl daemon-reload
sudo systemctl enable beszel-agent.service
sudo systemctl start beszel-agent.service

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#homelab Browse homelab catalog → #monitoring Browse monitoring catalog → #self-hosted Browse self-hosted catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →