Agent Installation

Beszel Agent supports installation via Docker / Podman, single binary file, Homebrew package, Scoop package, 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, use software like WireGuard, Tailscale (video instructions), Cloudflare Tunnel (instructions), or Pangolin 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.ymldocker runpodman run

yaml

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:
      LISTEN: 45876
      KEY: '<public key>'

bash

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 LISTEN=45876 \
  henrygd/beszel-agent:latest

bash

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 LISTEN=45876 \
  docker.io/henrygd/beszel-agent:latest

Why host network mode?

The agent must use host network mode to access the host's network interface stats. This automatically exposes the port, so change the port using an environment variable if needed.

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

When connecting to a local agent, localhost will not work because the containers are in different networks. See the Getting Started guide for an example of how to connect using a unix socket.

Binary

Beszel is written in pure Go and can be easily compiled (or cross-compiled) if a prebuilt binary isn't available.

1. Linux install script

Root privileges required

The script needs root privileges to create a beszel user and set up a service to keep the agent running after reboot. The agent process itself does not run as root.

The script installs the latest binary and optionally enables automatic daily updates.

-k: Public key (enclose in quotes; interactive if not provided)
-p: Port or address (default: 45876)
-u: Uninstall
--auto-update: Enable or disable automatic daily updates (interactive if not provided)
--china-mirrors: Use GitHub mirror to resolve network issues in mainland China
-h: Show help

bash

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && /tmp/install-agent.sh

2. Manual download and start (Linux, FreeBSD, others)

Click to expand/collapse

Download the binary

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

bash

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

Use -h to see all available options.

bash

./beszel-agent -listen "45876" -key "<public key>"

Update the agent

bash

./beszel-agent update

Create a service (optional)

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

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

ini

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

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

# Security/sandboxing settings
KeyringMode=private
LockPersonality=yes
NoNewPrivileges=yes
ProtectClock=yes
ProtectHome=read-only
ProtectHostname=yes
ProtectKernelLogs=yes
ProtectSystem=strict
RemoveIPC=yes
RestrictSUIDSGID=true
SystemCallArchitectures=native

[Install]
WantedBy=multi-user.target

Enable and start the service.

bash

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

3. Manual compile and start (any platform)

Click to expand/collapse

Compile

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

Start the agent

Use -h to see all available options.

bash

./beszel-agent -listen "45876" -key "<public key>"

Update the agent

bash

./beszel-agent update

Create a service (optional)

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

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

ini

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

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

# Security/sandboxing settings
KeyringMode=private
LockPersonality=yes
NoNewPrivileges=yes
ProtectClock=yes
ProtectHome=read-only
ProtectHostname=yes
ProtectKernelLogs=yes
ProtectSystem=strict
RemoveIPC=yes
RestrictSUIDSGID=true
SystemCallArchitectures=native

[Install]
WantedBy=multi-user.target

Enable and start the service.

bash

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

Homebrew (macOS, Linux)

Environment variables can be changed in ~/.config/beszel/beszel-agent.env.

Logs are written to ~/.cache/beszel/beszel-agent.log.

Homebrew install script

-k: SSH key (interactive if not provided)
-p: Port (default: 45876)
-h: Show help

bash

curl -sL https://get.beszel.dev/brew -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && /tmp/install-agent.sh

Homebrew manual install

bash

mkdir -p ~/.config/beszel ~/.cache/beszel
echo 'KEY="ssh-ed25519 AAAA..."' > ~/.config/beszel/beszel-agent.env
brew tap henrygd/beszel
brew install beszel-agent
brew services start beszel-agent

WinGet / Scoop (Windows)

The agent is available as a package in WinGet and Scoop.

The script below uses Scoop if you have it installed, otherwise it uses WinGet if that's installed. If neither are available, it will install both Scoop and the agent.

It also installs NSSM and creates a service to keep the agent running after reboot.

-Key: SSH key (interactive if not provided)
-Port: Port (default: 45876)

powershell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser; & iwr -useb https://get.beszel.dev -OutFile "$env:TEMP\install-agent.ps1"; & "$env:TEMP\install-agent.ps1"

The script's source code is available on GitHub.

Edit configuration

Edit the service in NSSM by running the command below. Scroll to the right in the GUI to find environment variables.

powershell

nssm edit beszel-agent

You can also change options directly from the command line:

powershell

nssm set beszel-agent AppEnvironmentExtra "+EXTRA_FILESYSTEMS=D:,E:"

Restart the service when finished: nssm restart beszel-agent

Logs

Logs are saved in C:\ProgramData\beszel-agent\logs.

Upgrade

Scoop

powershell

nssm stop beszel-agent; & scoop update beszel-agent; & nssm start beszel-agent

WinGet

powershell

nssm stop beszel-agent; & winget upgrade henrygd.beszel-agent; & nssm start beszel-agent

Uninstall

Scoop

powershell

nssm stop beszel-agent
nssm remove beszel-agent confirm
scoop uninstall beszel-agent

WinGet

powershell

nssm stop beszel-agent
nssm remove beszel-agent confirm
winget uninstall henrygd.beszel-agent

FreeBSD / OPNSense

A FreeBSD port is on the roadmap but not yet available (contributions welcome!). We'll also add FreeBSD compatibility to the main install script.

For now, the agent can be installed manually. See the following for more information:

Home Assistant

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

Agent Installation ​

Requirements ​

Using the Hub ​

Docker or Podman ​

Why host network mode? ​

Binary ​

1. Linux install script ​

2. Manual download and start (Linux, FreeBSD, others) ​

Download the binary ​

Start the agent ​

Update the agent ​

Create a service (optional) ​

3. Manual compile and start (any platform) ​

Compile ​

Start the agent ​

Update the agent ​

Create a service (optional) ​

Homebrew (macOS, Linux) ​

Homebrew install script ​

Homebrew manual install ​

WinGet / Scoop (Windows) ​

Edit configuration ​

Logs ​

Upgrade ​

Scoop ​

WinGet ​

Uninstall ​

Scoop ​

WinGet ​

FreeBSD / OPNSense ​

Home Assistant ​

Agent Installation

Requirements

Using the Hub

Docker or Podman

Why host network mode?

Binary

1. Linux install script

2. Manual download and start (Linux, FreeBSD, others)

Download the binary

Start the agent

Update the agent

Create a service (optional)

3. Manual compile and start (any platform)

Compile

Start the agent

Update the agent

Create a service (optional)

Homebrew (macOS, Linux)

Homebrew install script

Homebrew manual install

WinGet / Scoop (Windows)

Edit configuration

Logs

Upgrade

Scoop

WinGet

Uninstall

Scoop

WinGet

FreeBSD / OPNSense

Home Assistant