# Windows agent

Reports a Windows machine to Homelab Manager the same way the [Linux agent](../linux/) does: its
scheduled tasks, plus hostname, IP addresses, CPU / memory / disk usage and listening ports. It
runs as a scheduled task (as SYSTEM, every 15 minutes) and pushes to `POST /api/agent/report`, so
the machine never needs to be reachable from Homelab Manager.

## Install

1. In Homelab Manager, **Servers → Manage servers → Add a server**, choose **Windows** as the
   operating system, and copy the install command shown once for the new token.
2. On the Windows machine, open **Windows PowerShell as administrator** and paste it. It looks like:

   ```powershell
   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   $env:API_URL = 'https://homelab.example.lan'; $env:API_TOKEN = 'hlm_xxx'
   iex ((New-Object Net.WebClient).DownloadString("$env:API_URL/agent/windows/install.ps1"))
   ```

The installer downloads the agent to `C:\ProgramData\HomelabManager\`, stores the URL and token
there in `agent.json` (readable only by SYSTEM and Administrators), registers a scheduled task named
**Homelab Manager Agent**, and sends a first report so you see straight away whether it worked.

If Homelab Manager uses a **self-signed certificate**, tick the box in the Servers page: the command
then also skips certificate checks for the download and sets `API_INSECURE`, which makes the agent
skip them for every report. Only do that on a trusted LAN. That form is for Windows PowerShell 5.1
(the one built into Windows); in PowerShell 7 use `-SkipCertificateCheck` for the download step.

Set `INTERVAL_MINUTES` before installing to report more or less often (default 15).

## What it reports

- **Scheduled tasks** — name, what they run (program and arguments), a readable description of their
  triggers ("Daily at 02:00", "Weekly on Mon, Wed at 03:00", "At logon", "…, repeating every 15 min"),
  next run time and whether they're enabled. They show up under *Windows scheduled tasks*. Microsoft's
  own tasks (the `\Microsoft\` folder — several hundred) are left out; set `INCLUDE_MICROSOFT_TASKS=true`
  (environment variable, or `"includeMicrosoftTasks": true` in `agent.json`) to report them too.
- **System** — IPv4 addresses (not loopback or 169.254.x), CPU model, cores and current processor load,
  memory, and every fixed disk (`C:`, `D:`, …).
- **Listening ports** — TCP listeners and UDP endpoints with the program that owns them, so they appear
  on the server's Ports card, including services bound to localhost only.

Unlike the Linux agent's CPU figure (a load average), the Windows one is the processor's actual
current load.

## Try it without installing

```powershell
$env:API_URL = 'https://homelab.example.lan'; $env:API_TOKEN = 'hlm_xxx'
.\report-tasks.ps1 -DryRun     # prints the JSON it would send, sends nothing
.\report-tasks.ps1             # sends one report
```

Works in Windows PowerShell 5.1 and PowerShell 7, with or without administrator rights.

## Check on it

```powershell
Get-ScheduledTaskInfo -TaskName 'Homelab Manager Agent'   # LastRunTime, LastTaskResult (0 = fine)
Start-ScheduledTask   -TaskName 'Homelab Manager Agent'   # run it now
```

## Uninstall

In an elevated Windows PowerShell (the Servers page shows the exact command for that server):

```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
iex ((New-Object Net.WebClient).DownloadString('https://homelab.example.lan/agent/windows/uninstall.ps1'))
```

This removes the scheduled task, the agent script and `agent.json`. The server's entry and history in
Homelab Manager are kept — delete it from the Servers page if you no longer want it tracked.

## Notes

- Written for Windows 10 / Windows Server 2016 or newer. Older releases are untested; the repeating trigger
  is created without an end date, which very old Task Scheduler versions may not accept.
- The scripts in this folder are deliberately plain ASCII: they're downloaded as text, and Windows
  PowerShell 5.1 reads a file without a byte-order mark as ANSI, so anything else would be garbled.
- Task names, commands and ports are sent to your Homelab Manager server; see its Privacy page for what
  it stores.