Hub Installation

Beszel supports installation via Docker/ Podman or single binary file.

TIP

Check the Getting Started guide if you're setting up Beszel for the first time.

Docker or Podman

All methods will start the Beszel service on port 8090 and mount the ./beszel_data directory for persistent storage.

docker-compose.yml

services:
  beszel:
    image: henrygd/beszel
    container_name: beszel
    restart: unless-stopped
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data

docker run

mkdir -p ./beszel_data && \
docker run -d \
  --name beszel \
  --restart=unless-stopped \
  -v ./beszel_data:/beszel_data \
  -p 8090:8090 \
  henrygd/beszel

podman run

mkdir -p ./beszel_data && \
podman run -d \
  --name beszel \
  --restart=unless-stopped \
  -v ./beszel_data:/beszel_data \
  -p 8090:8090 \
  docker.io/henrygd/beszel

Click to view complete docker-compose.yml config including local agent

IMPORTANT

This configuration should work out of the box, but you must follow these steps when adding the system in the web UI:

1. Update the KEY value with your public key, then run docker compose up -d again to restart the agent.

2. Use host.docker.internal as the Host / IP. Do not use localhost or 127.0.0.1.

docker-compose.yml

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    extra_hosts:
      - host.docker.internal:host-gateway
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      PORT: 45876
      # Do not remove quotes around the key
      KEY: 'UPDATE WITH YOUR PUBLIC KEY (copy from "Add system" dialog)'

Click to view instructions for running docker compose

NOTE

If you prefer to set up containers in a different way, please feel free to do so.

1. Install Docker and Docker Compose if you haven't already.

2. Copy the docker-compose.yml content.

3. Create a directory somewhere to store the docker-compose.yml file.

mkdir beszel
cd beszel

4. Create a docker-compose.yml file, paste in the content, and save it.

nano

nano docker-compose.yml

vim

vim docker-compose.yml

emacs

emacs docker-compose.yml

vscode

code docker-compose.yml

5. Start the service.

docker compose up -d

Binary

There are multiple ways to install the binary. Choose your preference below.

1. Quick script (Linux)

This command downloads and runs our install-hub.sh script. The script installs the latest binary and creates a systemd service to keep it running after reboot.

• -u : Uninstall
• -p <port> : Specify a port number (default: 8090)

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

2. Manual download and start

Click to expand/collapse

Download

Download the latest binary from releases that matches your server's CPU architecture and run it manually. You will need to create a service manually to keep it running after reboot.

curl -sL "https://github.com/henrygd/beszel/releases/latest/download/beszel_$(uname -s)_$(uname -m | sed 's/x86_64/amd64/' | sed 's/armv7l/arm/' | sed 's/aarch64/arm64/').tar.gz" | tar -xz -O beszel | tee ./beszel >/dev/null && chmod +x beszel

Start the hub

./beszel serve --http "0.0.0.0:8090"

Update the hub

./beszel update

Create a service (optional)

If your system uses systemd, you can create a service to keep the hub running after reboot.

1. Create a service file in /etc/systemd/system/beszel.service.

[Unit]
Description=Beszel Hub
After=network.target

[Service]
Type=simple
Restart=always
RestartSec=3
User=root
WorkingDirectory={/path/to/working/directory}
ExecStart={/path/to/working/directory}/beszel serve --http "0.0.0.0:8090"

[Install]
WantedBy=multi-user.target

2. Enable and start the service.

sudo systemctl daemon-reload
sudo systemctl enable beszel.service
sudo systemctl start beszel.service

3. Manual compile and start

Click to expand/collapse

Compile

See Compiling for information on how to compile the hub yourself.

Start the hub

./beszel serve --http "0.0.0.0:8090"

Update the hub

./beszel update

Create a service (optional)

If your system uses systemd, you can create a service to keep the hub running after reboot.

1. Create a service file in /etc/systemd/system/beszel.service.

[Unit]
Description=Beszel Hub
After=network.target

[Service]
Type=simple
Restart=always
RestartSec=5
User=root
WorkingDirectory={/path/to/working/directory}
ExecStart={/path/to/working/directory}/beszel serve --http "0.0.0.0:8090"

[Install]
WantedBy=multi-user.target

2. Enable and start the service.

sudo systemctl daemon-reload
sudo systemctl enable beszel.service
sudo systemctl start beszel.service