Skip to main content

Beszel Agent Installation (Linux)

This Knowledge Base (KB) article is designed for internal documentation[cite: 1]. It outlines the streamlined "nuke and pave" installation method, perfected for Ubuntu Server environments, ensuring a clean deployment every time [cite: 2].

  • Target Systems: Ubuntu Server / Debian-based distributions [cite: 4]
  • Hardware Optimization: 7th-Gen Intel Core i5 | 16GB DDR4 | NVMe SSD [cite: 5]
  • Default Port: 45876 [cite: 6]

1. Prerequisites

Before beginning the installation, verify the following requirements:

  • Connectivity: Ensure the target system can communicate with the Beszel Hub (CasaOS) on the local network[cite: 8].
  • Static IP: Confirm the target server has a DHCP reservation or a static IP assigned[cite: 9].
  • Firewall: Port 45876 must be open for inbound TCP traffic[cite: 10].

2. Installation Command (Master)

The following command uses the official Beszel automated script [cite: 11, 12]. This process creates a dedicated unprivileged beszel user downloads the latest binary and configures the systemd service with your specific public key[cite: 12].

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && \
chmod +x /tmp/install-agent.sh && \
sudo /tmp/install-agent.sh -p 45876 -k "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICJ7lFlWxcv1b25gymPNRAvp0ptAJChTuNYvmnomZpFW"

Source: [cite: 14]

3. Post-Installation Configuration

Immediately after running the installation script, execute these commands to ensure network stability and service health[cite: 16].

A. Open Firewall (UFW)

sudo ufw allow 45876/tcp
sudo ufw reload

Source: [cite: 19]

B. Verify Service Status

Ensure the agent is active and not stuck in a crash loop[cite: 21].

sudo systemctl status beszel-agent.service

Source: [cite: 23]

4. Troubleshooting & Maintenance

Clean Uninstall (Nuke & Pave)

If the agent fails to start due to a malformed key or configuration error, run this sequence to completely purge the installation before retrying Step 2[cite: 25, 26]:

sudo systemctl stop beszel-agent.service
sudo rm -f /etc/systemd/system/beszel-agent.service
sudo rm -rf /opt/beszel-agent
sudo userdel beszel
sudo systemctl daemon-reload

Source: [cite: 28]

Log Inspection

To view live logs for connection rejections or hardware sensor errors[cite: 29, 30]:

sudo journalctl -u beszel-agent.service -f --no-pager

Source: [cite: 32]

NVMe Health Note

The Beszel agent has a negligible I/O footprint[cite: 34]. To maintain the performance of your 256GB NVMe SSD, ensure the fstrim timer is active alongside the agent[cite: 34]:

sudo systemctl enable --now fstrim.timer

Source: [cite: 36]

Back to top