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)
`installProfile.id`	`"twincore"` or `null`	Hosted install profile id, when applied
`installProfile.version`	`"1.0.0"` or `null`	Profile version
`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. Higher-priority sources win: environment variable beats config file beats database setting.

1. Admin UI (recommended for running instances)

Open Admin → Settings.
Enable Operational 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. Install profile

A hosted install profile can pre-set telemetry for organizations that want it on (or off) consistently across their installations. The profile’s telemetry section is applied to the database during install — see Hosted install profile.

5. 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 → Settings, turn operational telemetry off, save. The instance stops sending heartbeats immediately after the setting is applied. You can also unset SEQDESK_TELEMETRY_ENABLED or set telemetry.enabled = false in the config file and restart.

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.