Troubleshooting & Installing Beszel Agent (Windows)

This Knowledge Base (KB) article documents the WinSW (Windows Service Wrapper) method. This approach was specifically developed to bypass NSSM infrastructure outages and to resolve the common "Port already in use" error caused by orphaned background processes 

1. Overview

When standard installers or NSSM fail due to network outages or orphaned processes, the WinSW method provides a robust, self-contained way to run the Beszel Agent as a background system service. This ensures the agent starts automatically on boot and recovers from crashes without user intervention.

---

2. Phase 1: The "Nuke" (Cleanup)

If you previously tried to run the agent via a .bat file or another service manager, you must terminate any orphaned processes and remove the old service registration to free up Port 45876.

Open an Administrator PowerShell and run.

cd C:\Beszel

# 1. Stop and uninstall the service wrapper if it exists
.\beszel-service.exe stop 2>$null
.\beszel-service.exe uninstall 2>$null

# 2. Forcefully kill any invisible background agent processes
Stop-Process -Name "beszel-agent" -Force -ErrorAction SilentlyContinue
Stop-Process -Name "agent" -Force -ErrorAction SilentlyContinue

---

3. Phase 2: The "Pave" (Installation)

This script automates the creation of the directory, downloads the wrapper from GitHub (bypassing the unreliable NSSM site), and injects your unique CasaOS Public Key.

A. Automatic Framework Script

Run this in your Administrator PowerShell.

$installPath = "C:\Beszel"

# 1. Create the directory
New-Item -Path $installPath -ItemType Directory -Force | Out-Null

# 2. Download WinSW from GitHub
Invoke-WebRequest -Uri "https://github.com/winsw/winsw/releases/download/v2.12.0/WinSW-x64.exe" -OutFile "$installPath\beszel-service.exe"

# 3. Create the XML configuration with your Public Key
$xmlContent = @"
<service>
  <id>beszelagent</id>
  <name>Beszel Agent</name>
  <description>Lightweight monitoring agent for CasaOS Hub</description>
  <executable>$installPath\beszel-agent.exe</executable>
  <env name="KEY" value="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICJ7lFlWxcv1b25gymPNRAvp0ptAJChTuNYvmnomZpFW"/>
  <env name="PORT" value="45876"/>
  <log mode="roll"></log>
  <onfailure action="restart" delay="10 sec"/>
</service>
"@
Set-Content -Path "$installPath\beszel-service.xml" -Value $xmlContent

# 4. Open the Firewall
New-NetFirewallRule -DisplayName "Beszel Agent" -Direction Inbound -LocalPort 45876 -Protocol TCP -Action Allow -ErrorAction SilentlyContinue

B. Manual Binary Placement

1. Download the windows_amd64 agent from Beszel GitHub.
2. Move the file into C:\Beszel and rename it to exactly beszel-agent.exe.

---

4. Phase 3: Activation

Return to PowerShell and execute.

cd C:\Beszel
.\beszel-service.exe install
.\beszel-service.exe start

---

5. Verification Checklist

• Log Check: Verify that beszel-service.out and beszel-service.err files have been created in C:\Beszel
• Service Check: Run Get-Service beszelagent to ensure the status is Running.
• Hub Check: Add the system to your CasaOS Beszel dashboard using the Windows machine's IP address.

💡 Pro-Tip for Micro PCs
Because your micro PC relies on a 256GB NVMe SSD, the WinSW "roll" log mode is enabled in the XML above. This prevents log files from growing indefinitely and consuming unnecessary disk space, preserving the longevity of your drive.