Windows service

This service wrapper is for the Windows device agent. The control-plane API and background workers in this repo are documented separately and are not packaged here as Windows services.

1. From the repository root, create a virtual environment and install dependencies so the chosen interpreter has both the agent requirements and pywin32:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-agent.txt

1. Copy agent\config.windows.example.json to agent\config.json for a Windows-oriented starting point, or use agent\config.example.json if you prefer the shared cross-platform sample.

The sample config already uses __CURRENT_PYTHON__ for TPM and updater helper scripts. Keep that placeholder if you want those hooks to run with the same interpreter as the Windows service. The sample config leaves attestation_private_key_path, attestation_public_key_path, and update_signing_public_key_path blank so the default preflight works before you enable signed attestation or signed update manifests. The service wrapper also writes child agent output to agent\service.log by default. Set service_log_path in agent\config.json if you want that log somewhere else. The child Python process runs unbuffered so startup and crash details land in that file promptly. service_log_max_bytes defaults to 5242880 (5 MiB), and service_log_backup_count defaults to 3. When the log is larger than that at service start, Sentinel rotates it to service.log.1, shifting older generations up to the configured backup count.

Before you install the service, confirm that the paths referenced by server_url, cert_path, key_path, ca_path, and any optional attestation or update hook files all exist from the perspective of the service account. If you do want signed measurement attestation, generate deploy\certs\out\device_attest.key and deploy\certs\out\device_attest.pub first and then fill those config fields. If you want signed update manifests, generate deploy\updates\update_signing.pub and set update_signing_public_key_path to that file.

1. From the repository root, run the Windows preflight check before you install the service:

.\deploy\windows\preflight-agent-config.ps1

This validates agent\config.json, resolves helper command paths, checks referenced certificate and hook files, and prints the effective service log settings. If you use a different interpreter or config location, pass -PythonPath and -ConfigPath. The repository CI also runs this preflight on a Windows runner against agent\config.windows.example.json, so keep that sample config and the referenced helper paths current when you change the Windows deployment flow.

1. Before installing the service, validate the agent interactively once from the repository root:

.\.venv\Scripts\python.exe -m agent.agent_secure

1. From an elevated PowerShell prompt, prefer the one-step installer:

.\deploy\windows\install-agent-service.ps1

This runs the config preflight, installs the service with automatic startup, applies the SCM recovery policy, and runs the smoke test. Use -Reinstall if you intentionally want to replace an existing service registration. Pass -DryRun to validate config and preview the install, recovery, and smoke-test commands without requiring elevation or changing the host.

If you prefer the manual path, from an elevated PowerShell prompt inside the agent directory install and start the service with the same interpreter:

..\.venv\Scripts\python.exe service.py install
..\.venv\Scripts\python.exe service.py start

1. To stop or remove the service later, prefer the one-step uninstall helper:

.\deploy\windows\uninstall-agent-service.ps1

This stops the service if it is still running, removes the service registration, and leaves the current service logs on disk by default. Pass -RemoveLogs if you also want to delete the configured service.log plus rotated generations, or -DryRun to preview the removal flow without changing the host.

If you prefer the manual path:

..\.venv\Scripts\python.exe service.py stop
..\.venv\Scripts\python.exe service.py remove

The service launches python -m agent.agent_secure from the repository root, so install it with the exact interpreter you plan to register.

If the child agent process exits unexpectedly, the service now exits too so standard Service Control Manager recovery actions can restart it. Check agent\service.log, agent\service.log.1, or your configured service_log_path for the child process output.

1. From the repository root, configure SCM restart-on-failure actions once the service is installed if you did not use the one-step installer:

.\deploy\windows\configure-service-recovery.ps1

Optional: override the restart delay or service name if needed:

.\deploy\windows\configure-service-recovery.ps1 -ServiceName SentinelSecureX -RestartDelayMilliseconds 10000

1. Run the local Windows smoke test after installation if you did not use the one-step installer:

.\deploy\windows\smoke-test-agent-service.ps1 -RestartService

This runs the same config preflight validator by default, checks that the service exists, reaches the Running state, shows the current SCM recovery policy, and tails the configured service log. If you need a different interpreter path, pass -PythonPath. Use -SkipPreflight only when you intentionally want to inspect an already-installed service without validating config first, or -DryRun to preview the smoke-test checks without requiring the service to exist yet.

Troubleshooting

• If you want to replace an existing Windows service registration in one pass, run .\deploy\windows\install-agent-service.ps1 -Reinstall.
• Use .\deploy\windows\install-agent-service.ps1 -DryRun to preview the one-step install flow before you request elevation.
• Use .\deploy\windows\smoke-test-agent-service.ps1 -DryRun to preview the smoke-test checks before a first install or while documenting a rollout.
• Use .\deploy\windows\uninstall-agent-service.ps1 -DryRun to preview the exact removal flow before you stop a production agent.
• Re-run .\deploy\windows\preflight-agent-config.ps1 after any config, certificate, or helper-script change so path issues are caught before SCM restarts the service.
• Re-run .\.venv\Scripts\python.exe -m agent.agent_secure interactively if the service starts and stops immediately. Configuration, certificate, and TLS errors are easier to see there first.
• Check agent\service.log and rotated generations before opening Event Viewer; the child process output is usually the fastest signal.
• If the service reports Running but the control plane never sees heartbeats, verify the configured server_url, device certificates, local system time, and outbound firewall rules.
• If you change interpreters or move the repository, remove and reinstall the service so the SCM registration matches the current path layout.

Prefer configuring service recovery in the Service Control Manager instead of adding a custom watchdog loop.