Troubleshooting & Installing Beszel Agent (Windows)

This

Internal KnowledgeKB: BaseTroubleshooting & Installing Beszel Agent (KB)Windows)

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

WhenWindows standarddoes installersnot natively support Linux background commands (like nohup) or NSSMsystem faildaemons due(like tosystemd). network outages or orphaned processes, the WinSW method provides a robust, self-contained way toTo run the Beszel Agent asreliably ain the background systemso service.it survives reboots and user logouts, we use WinSW (Windows Service Wrapper). This ensuresmethod wraps the agentGo startsbinary automaticallyinto onan bootofficial andWindows recovers from crashes without user intervention.

---Service.

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

If you previously tried to run the agent via a .bat file or anotheraccidentally serviceran manager,Linux commands, you must terminatekill anythe orphaned processes and remove the old service registration to free up Port 45876.45876.

Open an Administrator PowerShell window and run.execute:

# 1. Create the directory if it doesn't exist
New-Item -Path "C:\Beszel" -ItemType Directory -Force | Out-Null
cd C:\Beszel

# 1.2. Stop and uninstall theany serviceexisting wrapper if it exists
.\beszel-service.exe stop 2>$null
.\beszel-service.exe uninstall 2>$null

# 2.3. 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: Binary Placement

Unlike Linux automated scripts, Windows requires you to manually place the agent executable.

Download the latest windows_amd64 agent from the Beszel GitHub Releases page. Extract the archive and move the executable into your C:\Beszel folder. Ensure the file is named exactly beszel-agent.exe.

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

With the binary in place, return to your Administrator PowerShell window. This script automates the creation of the directory, downloads the wrapperservice fromwrapper, GitHub (bypassingbuilds the unreliableXML NSSMconfiguration, site),opens the Windows Firewall, and injectsstarts yourthe unique CasaOS Public Key.

A. Automatic Framework Script

Run this in your Administrator PowerShell.service.

$installPath = "C:\Beszel"

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

# 2. Download WinSW from(The GitHubmodern Windows Service Wrapper)
Invoke-WebRequest -Uri "https://github.com/winsw/winsw/releases/download/v2.12.0/WinSW-x64.exe" -OutFile "$installPath\beszel-service.exe"

# 3.2. 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"<YOUR_HUB_PUBLIC_KEY_HERE>"/>
  <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.3. Open the Windows Firewall Port
New-NetFirewallRule -DisplayName "Beszel Agent" -Direction Inbound -LocalPort 45876 -Protocol TCP -Action Allow -ErrorAction SilentlyContinue

B.# Manual4. BinaryInstall Placement

and

DownloadStart the windows_amd64background agentservice from Beszel GitHub. 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$installPath
.\beszel-service.exe install
.\beszel-service.exe start

---

5. Verification Checklist

• Terminal Output: The PowerShell window should report Service 'Beszel Agent (beszelagent)' started successfully.

Log Check: VerifyLook thatinside C:\Beszel. You should now see beszel-service.out and beszel-service.err files havegenerated beenby createdthe in C:\Beszelwrapper. Service Check: Run Get-Service beszelagent to ensureverify the Windows Service status isreads Running.Running. Hub Check: Add the system to your CasaOS Beszel dashboard using the Windows machine's IP address.

---

💡Note: Pro-TipWindows foraggressively Micromanages PCs
Becausepower states. If your micro PC reliesgoes to sleep, the agent will pause and appear offline on athe 256GBHub. NVMeEnsure SSD,your Windows Power Plan is set to keep the WinSWsystem "roll"awake logif modeyou isrequire enabled24/7 in the XML above. This prevents log files from growing indefinitely and consuming unnecessary disk space, preserving the longevity of your drive.

monitoring.