Beszel Setup

Overview

Beszel is a lightweight, open-source system monitoring tool. It tracks CPU, memory, disk, and network usage over time with a clean, minimal dashboard.

Unlike service uptime monitors, which alert you when websites go down, Beszel shows you how your VPS resources are trending so you can spot problems before they cause outages.

Prerequisites

• Caddy running in Docker (see Caddy Setup)
• External caddy Docker network created

Docker Compose Setup

Create the Beszel directory:

sudo mkdir -p /opt/beszel
cd /opt/beszel

Create docker-compose.yml with both the Hub and Agent:

services:
  beszel:
    image: henrygd/beszel
    container_name: beszel
    restart: unless-stopped
    environment:
      APP_URL: http://localhost:8090
    ports:
      - "8090:8090"
    volumes:
      - ./beszel_data:/beszel_data
    networks:
      - caddy

  beszel-agent:
    image: henrygd/beszel-agent
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: 45876
      KEY: "<public-key>"
      HUB_URL: http://localhost:8090

networks:
  caddy:
    external: true

volumes:
  beszel_data:

Why network_mode: host for the agent? The agent needs direct access to the host’s network interface stats (bandwidth, connections, etc.). Host network mode gives the agent visibility into the real network. Without it, the agent only sees the container’s own network traffic, which isn’t useful for monitoring.

Get Your Agent Key

Before starting, you need the agent’s public key:

1. Start the Hub first (without the agent):

sudo docker compose up -d beszel

2. Visit https://beszel.<yourdomain>.com and create your admin account.

3. Click “Add System”, enter a name (e.g., vps), and click Add.

4. Copy the SSH public key shown — you’ll need it for the KEY value in the compose file above.

5. Edit docker-compose.yml and paste the key into the agent’s KEY environment variable.

Note: You can also generate a reusable token in the Beszel settings (/settings/tokens) and use TOKEN and HUB_URL env vars instead of pre-registering the system.

Start both services:

sudo docker compose up -d

Return to the Beszel dashboard. Your VPS metrics should appear within a few seconds.

Caddy Configuration

Add to your Caddyfile (/opt/caddy/Caddyfile):

beszel.<yourdomain>.com {
    reverse_proxy beszel:8090
}

Replace <yourdomain>.com with your actual domain.

Restart Caddy:

docker compose -f /opt/caddy/docker-compose.yml restart caddy

Access Beszel

Visit https://beszel.<yourdomain>.com to view your dashboard.

Security Note

By default, Docker publishes container ports to all network interfaces (0.0.0.0), which means the Beszel dashboard is accessible from the public internet on port 8090.

If you want to restrict Beszel to your Tailscale network only (recommended for monitoring dashboards), see Tailscale-Only Services.

Key Commands

docker compose -f /opt/beszel/docker-compose.yml up -d     # Start
docker compose -f /opt/beszel/docker-compose.yml down      # Stop
docker compose -f /opt/beszel/docker-compose.yml logs -f   # View logs

Data Persistence

Beszel stores its configuration and historical metrics in the beszel_data directory (bind-mounted from ./beszel_data). Data persists across container restarts and recreations.