Cross-platform native service integration (systemd / Windows SCM / launchd)

[xylo04]

Summary

kel-agent is described as a background service, but we should make it a first-class, OS-native system service across Linux, Windows, and macOS.
This issue proposes implementing a unified service lifecycle in Go, with platform-specific installation/boot persistence handled through a cross-platform library.

Goal

Provide a reliable, production-ready service mode that:

• Runs natively under each platform’s service manager
• Starts automatically at boot (or login, where appropriate)
• Supports install/uninstall/start/stop lifecycle commands
• Shuts down gracefully and logs appropriately per platform

Proposed approach

Use github.com/kardianos/service to abstract service registration and lifecycle across:

• Linux (systemd where available)
• Windows Service Control Manager (SCM)
• macOS launchd (LaunchDaemon/LaunchAgent)

This keeps one Go codepath for runtime behavior while delegating integration details to a proven library.

Scope of work

1) Refactor runtime into a service runner

• Move current long-running behavior into a structured runner (e.g., Run(ctx)).
• Introduce context-based cancellation for clean shutdown.
• Ensure all goroutines/resources are joined/closed on stop.

2) Add service wrapper

Implement kardianos/service program hooks:

• Start(service.Service) error → start worker in goroutine
• Stop(service.Service) error → cancel context, wait for graceful stop

3) Add lifecycle CLI commands

Add command support such as:

• kel-agent install
• kel-agent uninstall
• kel-agent start
• kel-agent stop
• kel-agent restart
• kel-agent run (foreground/dev mode)

4) Platform-aware paths and permissions

Standardize config/state/log locations per OS:

• Linux: /etc, /var/lib, /var/log (or distro-appropriate locations)
• macOS: /Library/... (daemon) or user Library (agent)
• Windows: %ProgramData% etc.

Run with least privilege by default where possible.

5) Logging + observability

• Foreground mode: stdout/stderr
• Service mode: integrate with platform logging expectations (journald/Event Log/launchd-captured logs)
• Add startup/shutdown/error lifecycle logs for troubleshooting

6) Boot persistence and restart behavior

• Ensure install enables startup persistence
• Configure restart-on-failure semantics where supported
• For Linux/systemd, document unit expectations (e.g., network ordering if required)

7) Packaging/documentation

• Add/update Make targets and docs for service lifecycle operations
• Document platform-specific caveats:
  • Windows session-0/non-interactive service model
  • macOS LaunchDaemon vs LaunchAgent tradeoffs
  • Linux service user and unit dependencies

Deliverables

• Service runner abstraction with graceful shutdown
• kardianos/service integration in main entrypoint
• CLI lifecycle commands implemented
• OS-specific path strategy implemented
• Logging behavior verified in foreground + service mode
• Boot persistence verified on Linux/Windows/macOS
• README/service docs updated with install and operations guide

Acceptance criteria

• kel-agent can be installed and managed as a native service on Linux, Windows, and macOS.
• Service auto-start works after reboot.
• Stop/restart operations are graceful and do not leak resources.
• Operational logs are accessible via expected platform mechanisms.
• Foreground mode remains available for local debugging/development.

Notes / open questions

• On macOS, should we target only LaunchAgent (per-user login) or also LaunchDaemon (system-wide, boot)?