Agent Installation

Beszel Agent supports installation via Docker / Podman container, single binary file, or Home Assistant add-on.

TIP

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

Requirements

If the agent and hub are on different hosts, you may need to update the firewall on your agent system to allow incoming TCP connections on the agent's port.

Alternatively, you can use software like Wireguard or Cloudflare Tunnel (instructions) to securely bypass the firewall.

Using the Hub

The docker-compose.yml or binary install command is provided for copy/paste in the hub's web UI when adding a new system.

Docker or Podman

TIP

Preconfigured docker-compose.yml content can be copied the hub's web UI when adding a new system, so in most cases you do not need to set this up manually.

docker-compose.yml

services:
  beszel-agent:
    image: henrygd/beszel-agent
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # monitor other disks / partitions by mounting a folder in /extra-filesystems
      # - /mnt/disk1/.beszel:/extra-filesystems/disk1:ro
    environment:
      PORT: 45876
      KEY: '<public key>'

docker run

docker run -d \
  --name beszel-agent \
  --network host \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e KEY="<public key>" \
  -e PORT=45876 \
  henrygd/beszel-agent:latest

podman run

podman run -d \
  --name beszel-agent \
  --network host \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e KEY="<public key>" \
  -e PORT=45876 \
  docker.io/henrygd/beszel-agent:latest

Why host network mode?

The agent must use host network mode to access network interface metrics, which automatically exposes the port. Change the port using an environment variable if needed.

If you don't need network stats, you can remove that line from the compose file and map the port manually.

Binary

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

1. Quick script (Linux)

TIP

A preconfigured command can be copied in the hub's web UI when adding a new system, so in most cases you do not need to run this command manually.

This command downloads and runs our install-agent.sh script.

The script installs the latest binary and creates a systemd service to keep it running after reboot. You may optionally enable automatic daily updates.

• -p: Port (default: 45876)
• -k: Public key (enclose in quotes; interactive if not provided)
• -u: Uninstall
• --china-mirrors: Use GitHub mirror to resolve network issues in mainland China

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

2. Manual download and start

Click to expand/collapse

Download the binary

Download the latest binary from releases that matches your server's OS / architecture.

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

Start the agent

• PORT : Port
• KEY : Public Key

PORT=45876 KEY="<public key>" ./beszel-agent

Update the agent

./beszel-agent update

Create a service (optional)

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

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

[Unit]
Description=Beszel Agent Service
After=network.target

[Service]
Environment="PORT=$PORT"
Environment="KEY=$KEY"
# Environment="EXTRA_FILESYSTEMS=sdb"
Restart=always
RestartSec=5
ExecStart={/path/to/working/directory}/beszel-agent

[Install]
WantedBy=multi-user.target

2. Enable and start the service.

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

3. Manual compile and start

Click to expand/collapse

Compile

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

Start the agent

• PORT : Port
• KEY : Public Key

PORT=45876 KEY="<public key>" ./beszel-agent

Update the agent

./beszel-agent update

Create a service (optional)

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

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

[Unit]
Description=Beszel Agent Service
After=network.target

[Service]
Environment="PORT=$PORT"
Environment="KEY=$KEY"
# Environment="EXTRA_FILESYSTEMS=sdb"
Restart=always
RestartSec=5
ExecStart={/path/to/working/directory}/beszel-agent

[Install]
WantedBy=multi-user.target

2. Enable and start the service.

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

Home Assistant

See the Home Assistant Agent page for instructions on setting up the agent as a Home Assistant add-on.