Skip to main content

Purging and Reinstalling Beszel Agent (Linux)

This Knowledge Base (KB) article documents the "Nuke and Pave" method. [cite: 1] This is the most reliable way to resolve "Invalid SSH Key" errors, service crashes, or corrupted configurations on your Ubuntu Server instances. [cite: 2]

Scenario: Use this procedure if the Beszel Hub shows a red "Offline" dot despite the service running, or if journalctl reports failed to parse key or illegal base64 data. [cite: 4]

Logic: This method forcefully terminates lingering processes, clears the systemd memory cache, and deletes the unprivileged user to ensure the new installation starts from a completely "zeroed" state. [cite: 5]

Phase 1: The "Nuke" (Complete Removal) [cite: 6]

Run this block to obliterate the existing installation. This is safe to run even if some files are already missing. [cite: 7]

# 1. Force kill any hung agent processes
sudo killall -9 beszel-agent 2>/dev/null

# 2. Stop and disable the service unit
sudo systemctl stop beszel-agent.service 2>/dev/null
sudo systemctl disable beszel-agent.service 2>/dev/null

# 3. Delete the service configuration and binary files
sudo rm -f /etc/systemd/system/beszel-agent.service
sudo rm -rf /opt/beszel-agent

# 4. Remove the dedicated agent user
sudo userdel beszel 2>/dev/null

# 5. Flush the systemd daemon cache
sudo systemctl daemon-reload

Phase 2: The "Pave" (Clean Reinstall) [cite: 10]

Execute the master installation command. This uses your verified Public Key to ensure an immediate handshake with the CasaOS Hub. [cite: 11]

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"

Phase 3: Post-Flight Verification [cite: 14]

After the script reports success, verify that the service is active and that the connection is established. [cite: 15]

1. Check Service Heartbeat [cite: 16]

sudo systemctl status beszel-agent.service

Target: Active: active (running) [cite: 19]

2. Verify Hub Communication [cite: 20]

sudo journalctl -u beszel-agent.service -n 20 --no-pager
  • Target: You should see INFO Starting SSH server addr=:45876. [cite: 23]
  • Target: You should not see any WARN messages regarding "Invalid SSH key." [cite: 24]

Admin Tips for the Micro PC Environment [cite: 25]

  • Hostname Resolution: If you see sudo: unable to resolve host, ensure your /etc/hosts file matches your hostname: [cite: 26]
    echo "127.0.1.1 $(hostname)" | sudo tee -a /etc/hosts [cite: 27]
  • NVMe Lifespan: By using the "Nuke and Pave" method only when troubleshooting, you avoid unnecessary write cycles on your 256GB NVMe SSD. [cite: 28] The agent itself runs primarily in RAM (approx. 6-10MB). [cite: 29]
  • Remote Management: If a server becomes unreachable during this process, use your JetKVM to access the tty console directly and verify the network interface with ip a. [cite: 30]

Next Step: Your Linux recovery documentation is complete. Shall we proceed with the Windows 11 agent installation using the NSSM service manager method?

Back to top