Agent on Windows

On Windows the installer registers the collector and a co-located VictoriaMetrics as Windows services. Run everything below from an elevated (Administrator) PowerShell. amd64 is supported.

Logs and traces on Windows

The agent receives logs and traces on Windows exactly as elsewhere, and demanded ones still reach LeanSignal. What Windows does not have yet is a local log or trace store — Loki and Tempo are installed on Linux and macOS only. The practical consequence is discovery: there is nothing local to browse, so demand selectors for logs and traces have to be written directly rather than picked from what the agent has seen.

Install

You need your tenant name and an agent key from the LeanSignal app (Agents → Add Agent).

$u = "https://raw.githubusercontent.com/LeanSignal/leansignal-agent/main/scripts/install/install.ps1"
Invoke-WebRequest $u -OutFile install.ps1
.\install.ps1 -AgentKey YOUR_KEY -AgentName this-host -Tenant YOUR_TENANT

Parameter	Meaning
-AgentKey	agent key (required)
-AgentName	labels this host’s telemetry with leansignal_agent_name (required)
-Tenant	tenant name (required for central mode) — every backend host is derived from it
-CentralUrl	install in edge mode, forwarding OTLP to a central agent
-Version	install a specific version (default: latest)
-NoVM	skip the local VictoriaMetrics

Advanced pins — set one only to bypass endpoint resolution for that host: -Domain, -Endpoint, -DataplaneEndpoint, -LokiEndpoint, -TempoEndpoint, -CcUrl, -ResolveAat. There is no -NoLoki / -NoTempo, because those stores are not installed on Windows.

Host metrics start flowing immediately. Confirm the agent is up:

Invoke-RestMethod http://127.0.0.1:13133/
Invoke-RestMethod http://127.0.0.1:8428/api/v1/label/__name__/values

What gets installed

Path	Contents
%ProgramFiles%\LeanSignal\Agent\	binaries
%ProgramData%\LeanSignal\Agent\config.yaml	collector configuration
%ProgramData%\LeanSignal\Agent\vm	local metrics data
LeanSignalAgent, LeanSignalVictoriaMetrics	the two Windows services

Configure

What	Where	Restart
Tenant, agent key, agent name	registry Environment on the LeanSignalAgent service	Restart-Service LeanSignalAgent
Collector pipeline (receivers, processors)	%ProgramData%\LeanSignal\Agent\config.yaml	Restart-Service LeanSignalAgent
Local metrics store	flags in the service binPath	Restart-Service LeanSignalVictoriaMetrics -Force

The simplest way to change tenant or rotate the key is to re-run the installer — it keeps your configuration and VictoriaMetrics data:

.\install.ps1 -AgentKey NEW_KEY -Tenant NEW_TENANT

Or set the registry value directly:

$k = 'HKLM:\SYSTEM\CurrentControlSet\Services\LeanSignalAgent'
Set-ItemProperty -Path $k -Name Environment -Value @(
  "LEANSIGNAL_TENANT=NEW_TENANT",
  "LEANSIGNAL_AGENT_KEY=NEW_KEY",
  "LEANSIGNAL_AGENT_NAME=this-host"
)
Restart-Service LeanSignalAgent

Changing tenant is a single value — the agent re-resolves its region and re-derives every endpoint on restart. See Agent configuration.

Manage the services

Two services. The agent depends on the VictoriaMetrics service, so stopping VM also stops the agent; the agent can be restarted on its own.

Get-Service LeanSignalAgent, LeanSignalVictoriaMetrics

# agent — VictoriaMetrics keeps running
Restart-Service LeanSignalAgent
Stop-Service    LeanSignalAgent
Start-Service   LeanSignalAgent

# VictoriaMetrics — also cycles the dependent agent
Restart-Service LeanSignalVictoriaMetrics -Force

Investigate logs

Unlike Linux (journald) and macOS (log files), the Windows services are created with sc.exe and do not capture the agent’s stderr — there is no log file to tail. Three ways to see what the agent is saying:

1. Service-level failures — won’t start, crashed, restarted:

Get-WinEvent -FilterHashtable @{LogName='System'; ProviderName='Service Control Manager'} -MaxEvents 20 |
  Where-Object { $_.Message -match 'LeanSignal' } | Format-List TimeCreated, Message

2. Full collector logs — stop the service and run it in the foreground. The service’s environment lives in the registry, so load it into the session first:

Stop-Service LeanSignalAgent
$k = 'HKLM:\SYSTEM\CurrentControlSet\Services\LeanSignalAgent'
(Get-ItemProperty -Path $k -Name Environment).Environment |
  ForEach-Object { $n,$v = $_ -split '=',2; Set-Item -Path "Env:$n" -Value $v }
& "$env:ProgramFiles\LeanSignal\Agent\leansignal-agent.exe" --config "$env:ProgramData\LeanSignal\Agent\config.yaml"
# Ctrl-C when done, then:
Start-Service LeanSignalAgent

3. In LeanSignal itself. The agent pushes its own logs through its own pipelines under service.name=leansignal-agent, so once a dashboard demands {service_name="leansignal-agent"} they are forwarded to your tenant and readable in the app — no console access needed. This is the only option that works without stopping the service, and the practical one for a fleet.

Query the local metrics store

# what exists locally
Invoke-RestMethod http://127.0.0.1:8428/api/v1/label/__name__/values

# is the control stream up? (1 = connected to LeanSignal)
Invoke-RestMethod "http://127.0.0.1:8428/api/v1/query?query=leansignal_edgecontroller_connection_up"

Extend the agent

The agent bundles the full OpenTelemetry Collector Contrib set, so you can add any receiver to %ProgramData%\LeanSignal\Agent\config.yaml and restart with Restart-Service LeanSignalAgent. The integration pages give you a ready-made receiver block and a matching demand.

Caution

Collecting a new source is only half of it. Until something demands the new data it stays on the host.

Upgrade and uninstall

.\upgrade.ps1                 # agent only — VictoriaMetrics and its data untouched
.\upgrade.ps1 -Version v0.7.0 # pin a version
.\upgrade.ps1 -WithVM         # also upgrade VictoriaMetrics (snapshots first)

Full detail lives in the Windows install guide in the agent repository.