Installing a watcher

Set up the Data Hub watcher on a lab instrument PC to monitor a directory, upload new files, and report run data to the web app.

ForLab operators

This guide covers the core install-to-running path for the watcher on an instrument PC: install, configure, start, and stop. For everything around it, see the related pages:

Run as a Windows service to keep it running across reboots.
Upgrading the watcher to stay current.
Troubleshooting when something doesn't work.
CLI reference and Configuration reference for every command and config field.

Prerequisites

uv: the recommended Python package manager. Install it if you don't have it yet; it handles Python for you, so you don't need a separate Python install.
A personal access token: it starts with dhub_. If you're a workspace admin you can create one at Settings > Access Tokens; if not, ask an admin to issue you one (you can't mint tokens yourself). See Managing tokens.
The watch directory: the folder where the instrument writes its output files.
File patterns: the file extensions you want to upload (e.g., *.csv, *.xlsx, *.tiff).

Installation

The watcher is published as a versioned package on PyPI. For use on lab PCs, install it directly from PyPI:

uv tool install data-hub-watcher

This installs the data-hub-watcher CLI into an isolated venv managed by uv, on PATH for any shell. Every example below that says data-hub-watcher … runs the installed CLI directly.

To run the watcher as a Windows service, install with the windows-service extra instead so the pywin32 dependency is included: uv tool install "data-hub-watcher[windows-service]". See Run as a Windows service.

Setup

Run the interactive setup wizard:

data-hub-watcher init

The wizard walks you through:

Environment: staging (testing), production, or preview. Choosing preview also prompts for the deployment's API base URL.
API key: paste your personal access token. It's saved to ~/.data-hub/.env.<environment>, so each environment keeps its own key. (You can also set DATA_HUB_API_KEY before running init to skip this prompt.)
Instrument: select an existing instrument, or register a new one. New instruments start as pending and must be activated by an admin before the watcher can start; see Adding an instrument.
Watch directory: the absolute path to the folder the instrument writes to.
File patterns: comma-separated globs (e.g., *.csv,*.xlsx). Only matching files are uploaded.
Run detection: how files are grouped into runs (prefix or directory). See Run detection.
Stability period: seconds a file must stay unchanged before it's considered fully written. Default 5.
Upload mode: auto (upload immediately) or manual (wait for server approval). See Upload modes.

The wizard saves your config to ~/.data-hub/config.yaml, the API key to ~/.data-hub/.env.<environment>, and syncs the config to the server.

The existing backlog. On staging and preview, the watcher does not upload files already in the watch directory when you first run init; it records them as a baseline and uploads only files created afterwards, so test environments aren't flooded with history. production uploads the backlog. To override, set initial_scan; see the Configuration reference.

Starting the watcher

First, verify your setup with a dry run:

data-hub-watcher watch --dry-run

This validates the config, checks that the API is reachable and the instrument is active, and previews what files would be uploaded, without starting the monitor.

When you're ready:

data-hub-watcher watch

The watcher will now:

Monitor the watch directory for new and modified files.
Wait for files to stabilize before processing them.
Group files into runs and report them to the API.
Upload files (in auto mode) or wait for server approval (in manual mode).
Send heartbeats every 60 seconds so the web dashboard shows watcher health.

Stopping the watcher

Press Ctrl+C in the terminal running watch. The watcher sends a final stopped heartbeat and exits cleanly. If you're running it as a Windows service, use data-hub-watcher service stop instead; see Run as a Windows service.

Changing configuration later

Re-run the wizard with current values as defaults, open the YAML directly, or print the current config:

data-hub-watcher config edit   # re-prompt each field
data-hub-watcher config open   # open the YAML in your editor
data-hub-watcher config show   # print the current config

Changes are synced to the server automatically. The full field-by-field breakdown is in the Configuration reference.