Quickstart
Go from nothing to your first uploaded run in about ten minutes: install the watcher, point it at your instrument's output folder, and start watching.
This is the fastest path from a fresh instrument PC to files showing up in the
Data Hub dashboard. It assumes someone has already given you an environment to
use (staging or production). Each step links to the full guide if you need
more detail.
Data Hub is self-hosted, so its backend must already be deployed and running before this walkthrough will work: the web app and REST API on Vercel, a PostgreSQL database, and the AWS infrastructure (S3 plus the processing Lambda). If that's not in place yet, an engineer needs to work through the first-time deployment guide in the data-hub developer docs first.
Before you start
You need three things:
- A personal access token: if you're not a Data Hub admin you can't mint one
yourself, so ask an admin to issue you a token (see Managing tokens).
It starts with
dhub_. - The watch directory: the folder your instrument writes its output files to.
- The file patterns: the globs you want to upload, e.g.
*.csv,*.xlsx,*.tiff.
1. Install the watcher
Install uv if you don't have it (it manages Python for you), then:
uv tool install data-hub-watcherOn Windows, if you plan to run the watcher as a service, install the extra now:
uv tool install "data-hub-watcher[windows-service]"See Installing a watcher for details.
2. Run the setup wizard
data-hub-watcher initThe wizard prompts for your environment, API key, instrument, watch directory,
file patterns, run detection, stability period, and upload mode. When asked for
the instrument, pick Register a new instrument if yours isn't listed yet;
it'll be created in a pending state.
3. Get the instrument activated
A new instrument can't upload until an admin confirms it. Ask your admin to open
Instruments in the web app and click Confirm next to it (the full flow is
in Adding an instrument). Once it shows active,
you're ready.
4. Dry-run, then start watching
Validate everything without uploading:
data-hub-watcher watch --dry-runThis checks the config, confirms the API is reachable and the instrument is active, and previews which files would be picked up. When it looks right:
data-hub-watcher watchThe watcher now detects new files, groups them into runs, uploads them, and sends
a heartbeat every 60 seconds. Your runs appear in the web dashboard moments after
upload. Press Ctrl+C to stop.
On staging and preview, the watcher records whatever is already in the watch
directory as a baseline and only uploads files created after setup, so a test
environment isn't flooded with a PC's entire history. production uploads the
existing backlog. See the Configuration reference
to change this.
Next steps
Overview
Data Hub automatically ingests, processes, and visualizes data generated by scientific instruments in the lab. Start here to install the watcher, manage access, and onboard instruments.
Concepts
Short definitions of the core Data Hub vocabulary: watcher, instrument, run, run detection, stability period, upload modes, heartbeats, and events.