Files
Homelab-manager/agent/windows
bobbanandClaude Sonnet 5.5 047fcb403e Harden the agents: keep the token off the command line, lock down their files
Linux: the token went to curl as an argument, readable by any local user in the process
list, and the reply was written to a fixed /tmp file that another user could replace with
a symlink (the agent runs as root). The token now goes to curl on stdin, and the payload
and reply live in a private mktemp directory that is removed afterwards. This also lifts
the limit on a report's size that a command-line argument imposed. The systemd unit now
runs with NoNewPrivileges, ProtectSystem=strict, PrivateTmp and similar restrictions
(it still sees every process, which is how it names the program behind a port).

Windows: the SYSTEM task's folder was left to inherit ProgramData's permissions. It now
gets explicit ones: SYSTEM and Administrators only.

Installed agents keep their own copy of the script, so each server needs the install
one-liner re-run to pick this up.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-06 22:05:17 +02:00
..
2026-09-27 00:09:00 +02:00
2026-09-27 00:09:00 +02:00

Windows agent

Reports a Windows machine to Homelab Manager the same way the Linux agent 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:

    [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

$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

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):

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