Run as a Windows service

Install and operate the Data Hub watcher as a Windows service so it starts automatically on boot, survives logouts, and auto-updates in the background.

ForLab operators

Running the watcher as a Windows service is the recommended setup for a permanent lab PC: it starts automatically on boot, keeps running after you log out, restarts itself on failure, and gets background auto-update for free.

Install the service extra

The service depends on pywin32, which ships in the windows-service extra. Install (or reinstall) the watcher with it:

uv tool install "data-hub-watcher[windows-service]"

Run data-hub-watcher init first if you haven't configured the watcher yet; the service uses the same ~/.data-hub/config.yaml and per-environment .env file.

Install and start

From an Administrator PowerShell:

data-hub-watcher service install
data-hub-watcher service start

service install registers the service to start automatically (delayed start, so it doesn't race the network stack at boot), configures restart-on-failure recovery actions, and registers the DataHubWatcherUpgrade Scheduled Task that the auto-updater uses.

The Windows auto-update path requires that service install (or service reinstall) has been run from an Administrator shell at least once: that's what registers the upgrade Scheduled Task. Fleet PCs upgrading into an auto-update-capable build for the first time need a one-time service reinstall to pick up the task.

Lifecycle commands

Command	What it does
`data-hub-watcher service install`	Register the service
`data-hub-watcher service start`	Start the service
`data-hub-watcher service stop`	Stop the service
`data-hub-watcher service status`	Show whether the service is running
`data-hub-watcher service uninstall`	Remove the service
`data-hub-watcher service reinstall`	Stop, uninstall, install, and start in one go

service reinstall is the right command after an out-of-band wheel swap (e.g. a manual uv tool install -U or pip install -U from an Administrator shell): the stop and uninstall steps are best-effort, so it works even if the service is already gone.

service install and service reinstall accept --env-path PATH to override which .env file the service loads (defaults to ~/.data-hub/.env.<environment>).

Don't run `watch` alongside the service

Running data-hub-watcher watch interactively while the service is also running is not supported: both processes would race on the same rotating log file and the same watch directory. Stop the service first if you need to run the CLI for debugging:

data-hub-watcher service stop
data-hub-watcher --verbose watch
data-hub-watcher service start   # when you're done

Where the service writes logs

The service and the CLI write to the same rotating log so a single tail covers both:

C:\ProgramData\DataHubWatcher\watcher.log

A separate service-bootstrap.log next to it captures crashes that happen before the service control dispatcher takes over (a missing pywin32, a moved venv, a corrupt install). To turn on debug logging without a reinstall, add DATA_HUB_WATCHER_LOG_LEVEL=DEBUG to the env file the service loads and restart the service.

For diagnosing a service that won't start or auto-update, see Troubleshooting.