How Hydrogen Desktop Auto-Updates

Hydrogen Desktop keeps itself, its skills, and its content current from the Adom Wiki. This page is the canonical inventory of every mechanism that phones home: what it fetches, when, how big the payload is, and how the schedules are designed so a large fleet cannot accidentally denial-of-service the wiki with synchronized requests.

The mechanisms

Update mode for #1 is user-controlled (Settings → Hydrogen Desktop → Updater): Normal shows a banner and you choose when to restart; Forced is reserved for important fixes; Off disables the check entirely.

Why the fleet cannot DoS the wiki (design rules)

1. Every periodic timer is launch-anchored, not wall-clock-anchored. A 4 h timer starts counting from the moment that particular machine launched HD. Launches are naturally spread out, so across a fleet the polls are approximately uniformly distributed in time. No timer fires "at the top of the hour" by design.
2. Manifests are tiny, binaries are fetched once. The recurring traffic is 1-10 KB manifest reads. The heavy installer download happens exactly once per released version per machine, gated by a SHA-256 comparison, and is spread across each machine's next 4 h poll window rather than all at once.
3. Activity gating. The container package hook fires on user prompts (throttled), so idle machines generate no traffic. The lightbulb background tick is additionally gated to business hours, and any user-driven check (menu open) debounces to 15 minutes and satisfies the background timer's freshness window too, so the two paths never double-poll.
4. Cloudflare fronts the wiki. The static file and download paths are CDN-cacheable, so even a correlated read burst of the same manifest mostly terminates at the edge.
5. Releases are gated before they are advertised. The release pipeline refuses to publish a version.json that points at a missing installer (HEAD-checked first), so the fleet is never sent chasing 404s on a retry loop.

Known herding risks (honest list, with status)

• Phase alignment after an update wave. When a release ships and the whole fleet restarts within a short window, every machine's launch-anchored 4 h timer becomes roughly phase-aligned and stays that way until the next uncorrelated restart. A fleet of N then polls the ~1 KB manifest in a burst every 4 h. At current fleet sizes this is noise, and the CDN absorbs it; at much larger scale the fix is jitter (below).
• Morning boot storms. Office machines powered on together Monday 9am launch together, which briefly correlates the launch-anchored timers. Same magnitude and mitigation as above.
• The business-hours gate clusters its opens. The lightbulb tick's Mon-Fri 7am-7pm gate means the subset of machines whose 30 min tick lands just after 7am local all fetch within that first half hour. Bounded by the tick spread, ~10 KB each, per timezone.
• Planned hardening (not yet implemented): add ±10-15% random jitter to the fixed intervals (HD updater, lightbulb tick, AD bridge sync), send If-None-Match/ETag on manifest reads so unchanged polls are 304s, and if the fleet grows large, stagger releases by advertising version.json to cohorts instead of everyone at once. Also planned: relax the app updater's 4 h poll to every 24 h once the release cadence settles (John 2026-07-24) — the 4 h cadence serves today's rapid pre-release iteration; a shipping product needs at most a daily check, which also cuts the fleet's steady-state traffic 6x.

For contributors

If you add ANY new periodic fetch to HD, follow the design rules above (launch-anchored, debounced, activity- or hours-gated where sensible, tiny manifest + fetch-once binary) and add it to the table on this page in the same PR.