# Windows

# Troubleshooting & Installing Beszel Agent (Windows)

# Internal KB: Troubleshooting & Installing Beszel Agent (Windows)

**Target Systems:** Windows 10 / Windows 11  
**Method:** WinSW (Windows Service Wrapper) via PowerShell  
**Primary Port:** `45876`

---

## 1. Overview

Windows does not natively support Linux background commands (like `nohup`) or system daemons (like `systemd`). To run the Beszel Agent reliably in the background so it survives reboots and user logouts, we use **WinSW (Windows Service Wrapper)**. This method wraps the Go binary into an official Windows Service.

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

If you previously tried to run the agent via a `.bat` file or accidentally ran Linux commands, you must kill the orphaned processes to free up Port `45876`.

Open an **Administrator PowerShell** window and execute:

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

# 2. Stop and uninstall any existing wrapper
.\beszel-service.exe stop 2>$null
.\beszel-service.exe uninstall 2>$null

# 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.

1. Download the latest `windows_amd64` agent from the [Beszel GitHub Releases page](https://github.com/henrygd/beszel/releases).
2. Extract the archive and move the executable into your `C:\Beszel` folder.
3. 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 downloads the service wrapper, builds the XML configuration, opens the Windows Firewall, and starts the service.

```powershell
$installPath = "C:\Beszel"

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

# 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="<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

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

# 4. Install and Start the background service
cd $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:** Look inside `C:\Beszel`. You should now see `beszel-service.out` and `beszel-service.err` files generated by the wrapper.
- **Service Check:** Run `Get-Service beszelagent` to verify the Windows Service status reads `Running`.
- **Hub Check:** Add the system to your CasaOS Beszel dashboard using the Windows machine's IP address.

---

***Note:** Windows aggressively manages power states. If your PC goes to sleep, the agent will pause and appear offline on the Hub. Ensure your Windows Power Plan is set to keep the system awake if you require 24/7 monitoring.*