Operational Telemetry

SeqDesk can send optional operational heartbeats to SeqDesk.com so the project team can see how many installations are active and what versions they run. Telemetry is off by default and must be turned on explicitly per instance.

What gets sent

When telemetry is enabled, the instance POSTs a small JSON payload to the configured endpoint. Every field is enumerated below — there are no other fields, no opaque “extras”, no user data.

Field	Example	Notes
`protocolVersion`	`1`	Heartbeat schema version
`instanceId`	`"3f1c0f0a-…"`	Stable random UUID generated when telemetry is first enabled
`runningVersion`	`"1.1.82"`	Currently running app version
`installedVersion`	`"1.1.82"`	Version on disk (may differ from `runningVersion` after an update before restart)
`update.available`	`true` / `false`	Whether the in-app updater sees a newer release
`update.latestVersion`	`"1.1.83"` or `null`	Latest seen by the updater
`database.provider`	`"postgresql"` / `"sqlite"` / `"unknown"`	Database backend
`runtime.platform`	`"linux"`	Result of `os.platform()`
`runtime.arch`	`"x64"`	Result of `os.arch()`
`runtime.nodeMajor`	`20`	Major Node.js version

A User-Agent: SeqDesk/<version> header and an X-SeqDesk-Telemetry-Token header are also sent. The receiver hashes the token and stores the heartbeat under the matching instanceId.

About “anonymous”

The payload is pseudonymous per install rather than fully anonymous: the instanceId is a stable UUID, so successive heartbeats from the same instance can be linked. It contains no user accounts, no email addresses, no host names, no IP addresses, no facility names, no sample/study/order metadata, no filenames, and no secrets.

Frequency

Heartbeats are throttled to one every 24 hours by default. The interval is configurable from 1 to 168 hours.

How to enable it

Telemetry can be enabled on any of these paths. The stored database setting wins over the config file and the installer defaults: SeqDesk uses the saved Admin setting first and only falls back to the config file (or installer-seeded value) when the database has no explicit choice.

The one exception is the kill switch: setting SEQDESK_TELEMETRY_DISABLED=true hard-overrides everything to off, regardless of the database or config value.

1. Admin UI (recommended for running instances)

Open Admin → Platform Info.
Under Feature Flags, enable SeqDesk telemetry.
Save. Heartbeats start within the next interval.

2. Environment variables

Set on the running app, then restart:


export SEQDESK_TELEMETRY_ENABLED=true
export SEQDESK_TELEMETRY_INTERVAL_HOURS=24                      # optional
export SEQDESK_TELEMETRY_ENDPOINT="https://www.seqdesk.com/api/telemetry/heartbeat"  # optional

See Environment Variables.

3. Config file

Add to seqdesk.config.json:


{
  "telemetry": {
    "enabled": true,
    "endpoint": "https://www.seqdesk.com/api/telemetry/heartbeat",
    "intervalHours": 24
  }
}

See Config File Reference.

4. Installer environment variables

Pass at install time to seed the initial setting:


seqdesk -y \
  --config ./infrastructure-setup.json \
  # SEQDESK_TELEMETRY_ENABLED=true and friends are read from the environment

How to disable it

Open Admin → Platform Info, turn SeqDesk telemetry off under Feature Flags, and save. The instance stops sending heartbeats immediately after the setting is applied.

Because the database setting takes precedence, the saved Admin choice cannot be overridden by SEQDESK_TELEMETRY_ENABLED or the config file. To force telemetry off regardless of the stored setting — for example in a locked-down deployment — set SEQDESK_TELEMETRY_DISABLED=true and restart; this kill switch overrides every other source.

Self-hosting the receiver

For private deployments that want telemetry visibility without sending to seqdesk.com, override telemetry.endpoint to point at your own server. The heartbeat schema is documented above; the public seqdesk.com receiver stores the same fields plus the hashed token in a telemetry_instances table.