Manage the watcher fleet

The Watchers area is the fleet view: every registered watcher, its health, deregistration, and (for manual upload mode) the upload queue. Cutting releases and advertising versions is separate: Roll out watcher releases.

Monitor watcher health

Each watcher sends a heartbeat every 60 seconds with version, instrument, watch directory, upload mode, activity counters, and uptime. The fleet list surfaces:

• Effective status: online vs offline from the last heartbeat
• Last heartbeat: a stale value is the first sign of a stopped, disconnected, or crashed watcher
• Hostname and instrument assignment
• Events: per-watcher log (watcher_started, run_reported, file_uploaded, update_*, and error with a details.kind discriminator)

Events are the primary remote-diagnosis tool. For operator-side symptoms, see Troubleshoot a watcher.

Deregister a watcher

Each instrument can have at most one active watcher. Deregister the old one when a PC is reimaged or replaced, or to clear “instrument already has an active watcher” on a new install.

• Web app: open the watcher under Watchers and click Deregister
• API: DELETE /api/v1/watchers/:watcherId (requires watchers:write)

Deregistration is a soft-delete: heartbeats, events, and runs stay under Watchers → Deregistered.

Retiring an instrument also deregisters its watchers automatically; see Retire an instrument.

Approving manual uploads

For instruments in manual upload mode, the watcher reports runs but waits for server approval before uploading file bytes. It polls the upload queue on each heartbeat and uploads files the server has marked for upload.

Safeguards that keep the queue healthy:

• Changing an instrument’s watch_directory reverts pending upload requests to detected so stale paths drain instead of erroring
• A queued file that keeps failing (missing on disk or failing to upload) is retried on at most three heartbeat polls, then cancelled server-side