Windows Agents¶

agent deploy and agent teardown are not supported on Windows.Those commands connect to the target host via SSH and rely on Unix system management (systemd, rc.d, or launchd). Windows agents require manual setup.

Step 1 - Register the agent¶

Register a Windows agent with --agent.node windows. Use --agent.logs.events to specify one or more Windows Event Log channels to collect from:

finchctl agent register \
  --agent.hostname win-server-01 \
  --agent.node windows \
  --agent.logs.events Application \
  --agent.logs.events System \
  --agent.metrics \
  --agent.config win-server-01.cfg \
  finch.example.com

This saves the Alloy configuration file to win-server-01.cfg on your local machine.

Common Windows Event Log channels¶

Channel	Contains
`Application`	Application errors and warnings
`System`	OS-level events, driver errors, service state changes
`Security`	Audit events (login attempts, privilege use)

Step 2 - Install Alloy on the Windows host¶

Download and run the PowerShell install script on the Windows host. The script fetches the latest alloy-windows-amd64.exe from GitHub Releases, extracts it to C:\Program Files\Alloy, and adds it to the system PATH:

# Run in an elevated (Administrator) PowerShell session
Invoke-RestMethod https://raw.githubusercontent.com/tschaefer/finchctl/main/contrib/install-latest-alloy.ps1 | Invoke-Expression

Alternatively, download the script and run it locally:

.\install-latest-alloy.ps1

Step 3 - Copy the config file¶

Copy the generated win-server-01.cfg to the Windows host:

C:\Program Files\Alloy\alloy.config

Step 4 - Run Alloy as a Windows service¶

Register Alloy as a Windows service using sc.exe, then start it:

# Run in an elevated (Administrator) PowerShell session
sc.exe create alloy binPath= "\"C:\Program Files\Alloy\alloy-windows-amd64.exe\" run --config.file=\"C:\Program Files\Alloy\alloy.config\"" start= auto
sc.exe start alloy

Alloy connects to the Finch service using the JWT in the config file and begins forwarding Windows Event Log entries and metrics.

Token renewal on Windows¶

When the agent token expires (365-day TTL), download a fresh config and copy it to the Windows host manually:

finchctl agent config \
  --agent.rid rid:finch:8d134b24c2541730:agent:59ddbb5d-73b2-45bf-95d3-5520dcf37618 \
  --agent.config win-server-01-renewed.cfg \
  finch.example.com

Then copy win-server-01-renewed.cfg to C:\Program Files\Alloy\alloy.config and restart the service:

sc.exe stop alloy
sc.exe start alloy