Windows service

Secronyx ships as a single .exe for Windows and can run four ways: interactively for a local MCP client over stdio, as an HTTP listener started by hand, as a Windows service installed by the binary itself, or as a service installed by the enterprise MSI. This page covers the last two, and the Windows-specific tool surface they expose.

The service subcommand

The binary contains a Service Control Manager client, so no wrapper such as NSSM is needed.

# Run as Administrator
secronyx service install
secronyx service start
secronyx service status
secronyx service stop
secronyx service uninstall

install creates a service whose image path is the absolute path of the running executable and whose arguments are service run followed by everything after --. The service is created with StartType: StartAutomatic, ErrorControl: ErrorNormal, display name Secronyx Agent and description System diagnostics agent for MCP SaaS. It then sets three recovery actions — restart after 5s, after 30s, then after 60s — with the failure count resetting after 86400 seconds. --name overrides the service name and is validated against ^[a-zA-Z][a-zA-Z0-9_-]{0,62}$ so it can never smuggle anything into a command line.

install, uninstall, start, stop and restart all require administrator rights, checked by running net session; status does not. uninstall stops the service first, waiting up to 30 seconds.

service run is what the SCM invokes. Run from a console it detects an interactive session and runs in the foreground with Ctrl+C handling, which is the fastest way to debug a startup problem.

What the service actually supports

This is the one place where the shipped help text is ahead of the code. secronyx --help offers:

secronyx service install -- --transport http --listen 0.0.0.0:8443 --api-key sk_xxx

The Windows service entry point (runMCPServer in cmd/secronyx/service_windows.go) parses a small flag set of its own and dispatches on --mode. Only --mode hybrid is implemented. With --transport http it logs

HTTP transport mode not yet implemented for Windows service
Use hybrid mode instead, or run the binary directly

and then waits for a stop signal without listening on anything. With no recognised mode it logs No valid mode specified, waiting for stop signal.... So a Windows service today means hybrid mode; a Windows HTTP listener means running the binary directly (from a scheduled task, a console, or your own service wrapper).

The flags the service entry point understands are --mode, --transport, --token, --api-key, --saas-url (default https://api.secronyx.com), --config-dir (default: the directory containing the executable), --ws-url (default wss://ws.secronyx.com/v1), --wakeup-url (default https://wakeup.secronyx.com), --instance-id, --device-token, --poll-timeout (10s), --idle-timeout (30s) and --debug. Anything else is a parse error logged to the Event Log.

secronyx service install --name secronyx -- --mode hybrid --api-key sk_xxx
secronyx service start

Running an HTTP listener directly

The exposure rules from Remote access over HTTP apply identically on Windows: a non-loopback listener needs both a 32-character-minimum token (or another method) and TLS.

$bytes = [byte[]]::new(32)
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$env:SECRONYX_TOKEN = [Convert]::ToBase64String($bytes)

.\secronyx.exe --transport http --listen 0.0.0.0:8443 `
  --tls-cert cert.pem --tls-key key.pem

New-NetFirewallRule -DisplayName "Secronyx" -Direction Inbound -LocalPort 8443 -Protocol TCP -Action Allow

The client then adds an Authorization: Bearer header; see Connect an AI client.

The enterprise MSI

deploy/windows/enterprise contains a WiX package that installs the same binary as a service called Secronyx running as LocalSystem, always in hybrid mode. The sources — Product.wxs, Service.wxs, Config.wxs and UI.wxs — use the WiX v4 schema, but build-msi.ps1 drives the WiX v3 tools: it looks for candle.exe and light.exe on PATH and stops with "WiX Toolset not found in PATH. Please install WiX Toolset v3.x" if they are missing. It also runs dotnet build -c Release for the C# custom actions unless -SkipCustomActions is passed, and validates the result with smoke.exe when that is on PATH.

.\build-msi.ps1 -Version "1.26.0" -BinaryPath <path to secronyx.exe> [-OutputPath <dir>]

-Version and -BinaryPath are mandatory. The output is secronyx-<version>.msi in -OutputPath, which defaults to the current directory.

Two installation paths are supported, distinguished by UILevel:

# Interactive: a wizard collects email and password and registers the device
msiexec /i secronyx.msi

# Silent: an API key registers the device at run time
msiexec /i secronyx.msi /qn API_KEY=sk_your_api_key_here
msiexec /i secronyx.msi /qn API_KEY=sk_xxx AGENT_NAME="PROD-WEB-01" /l*v install.log

A Launch condition enforces this: Installed OR (UILevel >= 4) OR (API_KEY <> ""), with the message "API_KEY property must be set for silent installation. Use: msiexec /i [msi] /qn API_KEY=your_api_key".

Properties

The resulting service arguments are assembled into SERVICE_ARGS before CostFinalize, always beginning service run --mode hybrid and always passing --config-dir "[INSTALLFOLDER].". A silent install appends --api-key [API_KEY]; an interactive install does not, because the wizard has already obtained a device token.

What gets installed

• secronyx.exe in INSTALLFOLDER
• config\agent.yaml from agent.yaml.template
• logs\ and credentials\, both with LocalSystem full control
• The Secronyx service, Start="auto", Account="LocalSystem", stopped on both install and uninstall and removed on uninstall
• HKLM\SOFTWARE\Secronyx with InstallPath, Version, SaasUrl, AgentName, WsUrl, WakeupUrl, InstanceId, PollTimeout, IdleTimeout
• An Event Log source at HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\secronyx with EventMessageFile pointing at the exe and TypesSupported = 7

Note that config\agent.yaml is a template for a future HTTP server mode (it describes listen: "0.0.0.0:8443", TLS files and enabled scopes). The hybrid service does not read it; its configuration is entirely in SERVICE_ARGS and the stored credentials.

The service is not auto-started by ServiceControl. A deferred custom action runs [SystemFolder]sc.exe start Secronyx, sequenced before InstallFinalize and conditioned on NOT Installed, after credentials have been written, so an interactive install never starts a service that has nothing to authenticate with.

Credentials

The interactive wizard's custom action stores a DPAPI-protected file at credentials\device.enc inside the install folder, machine-scoped. The Go side reads it through CryptUnprotectData and expects the PascalCase JSON that the C# custom action writes: DeviceToken, InstanceId, SaasUrl, Hostname, CreatedAt. A silent install has no such file: the API key stays in the service arguments, and the agent re-registers with it on every start, storing the returned instance ID and device token in its own credential file under the config directory. What is stored and what leaves the host is detailed in Hybrid and SaaS mode.

Test-Path "C:\Program Files\Secronyx\credentials\device.enc"

Logs and the Event Log

When the agent starts it calls InitLogger("secronyx"), which opens the Windows Event Log source of that name. If the source is not registered — a bare .exe copied onto a box, or a run before the MSI has installed — the open fails silently and the logger falls back to stdout, which for a service means nowhere useful. That is the single most common reason a hand-installed service appears to log nothing.

Event types map as Debug and Info to Information (event ID 1), Warning to Warning (2) and Error to Error (3).

Get-WinEvent -LogName Application -FilterXPath "*[System[Provider[@Name='secronyx']]]" -MaxEvents 50
Get-Service Secronyx | Format-List *

The Windows tool surface

Tools carry a scope, and the windows scope is the largest in the catalogue — 125 registered tools covering the registry, IIS (including FTP and ARR), DCOM and COM security, Active Directory, WMI health, VSS and shadow copies, Windows Error Reporting and reliability history, boot, firmware and TPM state, and assorted host queries such as mapped drives, user profiles, print jobs and SMB sessions. Hotfixes, installed programs and Windows features are not in it: get_windows_hotfixes, get_windows_programs and get_windows_features carry the software scope. Unlike sensitive, the windows scope is on by default in the binary (the default policy is every scope except sensitive); it is only the Helm chart that sets windows: false, since a Linux pod cannot serve it.

IIS coverage runs from the obvious (get_iis_sites, get_iis_app_pools, get_iis_bindings, get_iis_worker_processes, get_iis_site_state, get_iis_logging) to configuration detail (get_iis_request_filtering, get_iis_handlers, get_iis_modules, get_iis_aspnet_machinekey, get_iis_url_rewrite, get_iis_arr_routing, get_iis_ftp_ssl). Many accept an optional site_name, and the application-pool tools an optional app_pool_name, to filter results.

Windows Event Log reading is in the logs scope, not windows: get_event_log takes lines (default 50) and log_name (default System; Application, System and Security are the documented channels). Reading the Security channel requires a process privileged enough for it; the MSI service runs as LocalSystem.

Many tools can also be exercised from the command line without an MCP client, which is the quickest way to prove a permission problem is not a protocol problem. Not every registered tool has a --query case, so check runQuery() in cmd/secronyx/main.go — or just try it — before scripting against one:

.\secronyx.exe --query get_iis_sites --json
.\secronyx.exe --query get_iis_request_filtering --site-name "Default Web Site" --json
.\secronyx.exe --query get_iis_app_pool_recycling --app-pool DefaultAppPool --json
.\secronyx.exe --query get_registry_key --hive HKLM --regpath "SOFTWARE\Microsoft\Windows NT\CurrentVersion" --json
.\secronyx.exe --query get_event_log --json

Two things to know about --query. It is a direct collector call that bypasses MCP entirely, and its parameter coverage is not identical to the tools': get_event_log through --query always asks for 50 lines of the default channel and ignores --lines, and get_iis_app_pools ignores --app-pool (the per-pool detail queries above are the ones that use it). The application-pool detail queries are also spelled differently on the two surfaces - the MCP tool is get_iis_apppool_recycling, the --query name is get_iis_app_pool_recycling. Treat tools/list over the transport as the authoritative catalogue; see Command line and Tool reference.

A worked triage session is in Tutorial: triage a Windows IIS server. For rolling this out across many machines, see Fleet deployment.

Uninstalling

msiexec /x secronyx.msi /qn        # MSI install
secronyx service uninstall         # service subcommand install (as Administrator)

The MSI stops the service on both install and uninstall, removes it on uninstall, deletes the files it installed and cleans its registry entries. Neither path removes files the installer did not create.