Troubleshooting & Installing Beszel Agent (Windows)

This Knowledge Base (KB) article documents the WinSW (Windows Service Wrapper) method[cite: 1]. 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 [cite: 2].

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[cite: 8]. This ensures the agent starts automatically on boot and recovers from crashes without user intervention[cite: 9].

---

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 [cite: 11].

Open an Administrator PowerShell and run[cite: 12]:

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 [cite: 14]

---

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[cite: 16].

A. Automatic Framework Script

Run this in your Administrator PowerShell[cite: 18]:

$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 [cite: 20, 21, 22]

B. Manual Binary Placement

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

---

4. Phase 3: Activation

Return to PowerShell and execute[cite: 27]:

cd C:\Beszel
.\beszel-service.exe install
.\beszel-service.exe start [cite: 29]

---

5. Verification Checklist

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

💡 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[cite: 35]. This prevents log files from growing indefinitely and consuming unnecessary disk space, preserving the longevity of your drive[cite: 36].