Runtime Host

Appearance

Windows Service ​

Status: target state, not yet shipped. There is no Windows Service installer in the codebase today. The only Windows install path is the Local install. Service-Control-Manager registration is filed under launch backlog item P1.16b.

What ships today on Windows ​

The Host code itself is already Windows-aware. The supervisor sets windowsHide: true on every spawned runtime (projects/matrix-3/packages/host-service/src/matrix-host-service.ts:380-395) and on the NATS sibling spawn, so a flapping restart: always runtime does not pop a console window per restart. The bundled NATS lookup on Windows auto-appends .exe if the configured binaryPath does not have it (matrix-host-service.ts:1383-1394).

What ships:

  • hivecast install --home %USERPROFILE%\.matrix --http-port 3100
  • hivecast start --home %USERPROFILE%\.matrix
  • hivecast stop --home %USERPROFILE%\.matrix

Run these from PowerShell or cmd.exe. The Host runs as a normal user process; closing the shell that started it kills the Host.

What does not ship:

  • A Windows Service registration step.
  • Windows Event Log integration.
  • An MSI or other Windows installer.
  • A "start at login" entry.
  • Group-policy or domain-account integration.

Target state ​

A target Windows install would mirror the Linux .deb shape:

  1. Bundle Node, the host-service dist/, the NATS nats-server.exe, and the wrapper into C:\Program Files\HiveCast\.
  2. Add C:\Program Files\HiveCast\bin to the system PATH.
  3. Register two services with the Service Control Manager:
    • HiveCast NATS (hivecast-nats) — runs nats-server.exe -c nats-server.conf
    • HiveCast Host (hivecast-host) — runs node host-service\cli.js start with Requires=hivecast-nats (Windows equivalent: dependency listed in the service config).

A working installer would document:

powershell
# Manual registration (post-install) — sketch only, not a real shipped flow.
sc.exe create "HiveCast NATS" `
    binpath= "\"C:\Program Files\HiveCast\dist\bin\nats-server.exe\" -c \"C:\ProgramData\HiveCast\nats\nats-server.conf\"" `
    start= auto displayname= "HiveCast NATS"

sc.exe create "HiveCast Host" `
    binpath= "\"C:\Program Files\HiveCast\node\node.exe\" \"C:\Program Files\HiveCast\dist\host-service\cli.js\" start --home C:\ProgramData\HiveCast\host" `
    start= auto displayname= "HiveCast Host" `
    depend= "HiveCast NATS"

Start-Service "HiveCast NATS"
Start-Service "HiveCast Host"

Operator commands a target installer would document:

powershell
# Status
Get-Service "HiveCast Host","HiveCast NATS"

# Logs (target installer should wire to Windows Event Log)
Get-EventLog -LogName Application -Source "HiveCast Host"

# Restart
Restart-Service "HiveCast Host"

# Uninstall
Stop-Service  "HiveCast Host","HiveCast NATS"
sc.exe delete "HiveCast Host"
sc.exe delete "HiveCast NATS"

Open questions ​

A target installer would need to settle:

  • Service account: LocalSystem, NT SERVICE\HiveCast (managed account), or per-user. The Linux .deb chose a service user — equivalent on Windows is a managed service account.
  • Per-user vs per-machine install. macOS leans per-user; Linux leans per-machine; Windows can do either. The four-operational-units rule argues for per-Host-home, which translates to per-user on Windows.
  • Log rotation. There is no journald equivalent. Either ship pino or similar with size-based rotation, or write to Event Log with a size cap.
  • Firewall: by default Windows blocks inbound on the gateway port. The installer should prompt for a firewall rule on 127.0.0.1 only.
  • Bind address for shared dev: see the Linux postinst's HIVECAST_BIND_HOST heuristic at build-deb-installer.js:291-296. A Windows installer would copy that logic.

What's missing from the codebase ​

  • No *.wxs (WiX) or other Windows installer source.
  • No nssm/sc.exe integration helper.
  • No service-mode entry point in host-service/src/cli.ts (the existing start command runs in the foreground; a service host shim is expected).
  • No Windows-specific test under projects/matrix-3/packages/host-service/src/__tests__/.

See also ​