main
John Lauer Publish 0.1.0 d8a45ab

Hydrogen Self-Update on Linux: the app updates itself (a banner + an AI path)

This is how the Hydrogen app on the user's Linux computer stays current. It is NOT how the workspace tooling and skills update (those converge through adom-wiki pkg update and the adom/hook prompt hook), and NOT the editor extensions (their own reload banner). Don't confuse the three.

How it works

  1. The manifest. Hydrogen polls the wiki's version.json at startup, then every 4 hours on the public tier and every 8 hours on Insiders. The manifest has a linux section with up to three builds: deb, rpm, appimage.
  2. Which build applies: the kind this copy was installed with. It is an AppImage when $APPIMAGE is set; otherwise whichever of dpkg or rpm owns /usr/bin/adom-hydrogen. A copy from none of the three (a dev binary) cannot update itself.
  3. Download and stage in the background, verified by sha256 and size.
  4. The banner. Hydrogen shows "Restart to update (vX to vY)" only when the manifest has a newer build for THIS package kind. A newer version with no Linux build of this kind (or none at all) shows no banner; /updater/status then says why in not_installable, for example "1.0.720 is out, but its Linux .rpm is not published yet."
  5. The install (one click, or the AI path below):
    • .deb: apt-get install -y <file>.
    • .rpm: dnf install -y <file>, or rpm -U when dnf is not there.
    • Root comes from sudo -n first (never prompts; the package's sudoers rule covers admin users), then pkexec, which shows the desktop's password prompt (15 minutes to answer).
    • AppImage: the new file replaces the AppImage in place; no root needed.
    • VS Code's page is unloaded first so it saves its open tabs.
  6. Relaunch. A relauncher started as its own systemd-run --user unit (setsid when that is missing) waits for the old process to exit and starts the new build. Sign-ins (~/.config/hydrogen-desktop) and the workspace machine are not touched, so this session reconnects in a few seconds.
  7. When it fails, the banner shows the error with the command to run by hand (for example sudo apt-get install -y /tmp/<file>.deb). A cancelled password prompt changes nothing.

When to check

Check at the start of a session and whenever the user asks about updates. Don't poll constantly.

How to check (know both version numbers)

C=$(cat ~/.adom/hydrogen-control-url)
curl -s -X POST "$C/updater/check"   # same as Settings "Check now": re-poll and stage now
sleep 5; curl -s "$C/updater/status"

Returns { current_version, latest_version, update_available, staged, installable, not_installable, tier, ... }:

  • update_available: true → a newer Hydrogen exists.
  • installable: false: there is nothing this machine can install; tell the user the not_installable sentence, and do not offer to update.
  • staged: true: already downloaded and verified, so applying is quick.

What to do

If update_available and installable, tell the user both versions and ASK, and say that the install may ask for their password:

"Hydrogen vX to vY is available (already downloaded). Want me to install it and relaunch? Your computer may ask for your password. This workspace and our chat reconnect right after."

On explicit consent:

POST http://127.0.0.1:<control-port>/updater/install

It refuses (deferred: true, with busy) while an AI thread is mid-turn; pass {"force":true} only when the person agreed to cut that work off.

Rules

  • Consent-first. Never relaunch Hydrogen without the user's OK (it restarts their app). Pick a natural break — not mid-task.
  • State both versions (current → latest) so the user knows what's changing.
  • This updates the app shell only. Editor extensions/code-server use their own reload banner; in-workspace tooling/skills converge registry-native (adom-wiki pkg update via adom/hook). Don't confuse the three.
  • The password prompt is the user's: never try to answer or bypass it.

Resolving the control port

From inside the workspace, cat ~/.adom/hydrogen-control-url is the live URL (the control port is 47084 by default but rebinds to an ephemeral port when 47084 is taken, so never hardcode it). See the discovery ladder in hydrogen-ports (~/.config/hydrogen-desktop/ports.json on the host, ~/.adom/hydrogen-ports.json in the workspace, and the cloud KV fallback).