Concepts

A glossary of the nouns the rest of this documentation leans on. If you've landed mid-doc and a term is unfamiliar, it's probably defined here.

Instrument

A piece of lab equipment registered in Data Hub, identified by a kebab-case instrument ID (e.g. akta-fplc, bio-rad-cfx96). The ID is permanent (it becomes the storage key prefix and the identifier used across the system) and has a human-readable display name alongside it.

An instrument has three states:

See Adding an instrument and Managing instruments.

Watcher

The data-hub-watcher CLI agent that runs on an instrument PC. It monitors a directory, groups new files into runs, uploads them to cloud storage, and reports status to the API. Each instrument can have at most one active watcher at a time.

A watcher is registered with the API and carries one registration ID per environment. Deregistering a watcher is a soft-delete: its history stays visible for auditing. See Managing watchers.

Run

A logical grouping of files produced by one acquisition. The watcher assigns each file a run ID using its configured run detection method, then reports the run to the API. The first file for a run creates it; later files are added incrementally to the same run's manifest.

Run detection

The rule that maps a file to a run ID. Two broad strategies:

• Prefix: a regex extracts the run ID from the filename. The default ^([^_]+) takes everything before the first underscore, so RUN001_data.csv → RUN001.
• Directory: each subdirectory under the watch directory is its own run, so RUN001/data.csv → RUN001.

The full set of presets (and the custom-regex option) is in the Configuration reference.

Stability period

How many seconds a file must stay unchanged (same size and modification time) before the watcher treats it as fully written and eligible for upload. The default is 5 seconds; raise it for instruments that write large files slowly. A file that keeps changing for more than 5 minutes is abandoned with a stability_timeout error event.

Upload mode

How files get from the instrument to cloud storage:

• auto: files upload immediately after they're detected and stabilized.
• manual: runs are reported to the server, but files aren't uploaded until approved through the server-side upload queue (polled on each heartbeat). Use this when uploads need human approval.

Heartbeat

A status ping the watcher sends to the API every 60 seconds. It carries the watcher version, instrument ID, watch directory, upload mode, activity counters, and uptime, and is what drives the Last Heartbeat and online/offline health shown on the dashboard. The same tick also runs the auto-updater and (in manual mode) polls the upload queue.

Events

A per-watcher log of lifecycle moments and errors: watcher_started, run_reported, file_uploaded, update_succeeded, and error (with a details.kind discriminator), among others. Events are batched and flushed on each heartbeat and are visible on the dashboard, making them the primary tool for diagnosing a watcher remotely.

Environment

Which Data Hub deployment a watcher talks to: staging, production, or preview (a Vercel preview deployment, which needs an explicit API base URL). Staging and production are separate deployments with separate databases, so a single PC keeps an independent registration and local state per environment and can switch between them.

Initial scan

What the watcher does with files already sitting in the watch directory the first time an environment is entered. production uploads the existing backlog (full); staging and preview record it as a baseline and skip it (new-only) so test environments aren't flooded with history. See the Configuration reference.

Personal access token

A dhub_-prefixed bearer token that authenticates the watcher (and other API clients) with the Data Hub API. Tokens carry permission scopes and are created and revoked by admins. See Managing tokens and Security & permissions.