Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
d8a45ab
name: hydrogen-self-update description: >- How the Hydrogen app itself (not the workspace tooling) updates on Linux: the restart-to-update banner, the .deb/.rpm/AppImage install with sudo or the password prompt, and the consent-based AI path through /updater. Use when asked is there a Hydrogen update, update Hydrogen, what version of Hydrogen am I on, or relaunch to update.
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
- The manifest. Hydrogen polls the wiki's
version.jsonat startup, then every 4 hours on the public tier and every 8 hours on Insiders. The manifest has alinuxsection with up to three builds:deb,rpm,appimage. - Which build applies: the kind this copy was installed with. It is an AppImage when
$APPIMAGEis 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. - Download and stage in the background, verified by sha256 and size.
- 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/statusthen says why innot_installable, for example "1.0.720 is out, but its Linux .rpm is not published yet." - The install (one click, or the AI path below):
- .deb:
apt-get install -y <file>. - .rpm:
dnf install -y <file>, orrpm -Uwhen dnf is not there. - Root comes from
sudo -nfirst (never prompts; the package's sudoers rule covers admin users), thenpkexec, 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.
- .deb:
- Relaunch. A relauncher started as its own
systemd-run --userunit (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. - 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 thenot_installablesentence, 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 updateviaadom/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).
---
name: hydrogen-self-update
description: >-
How the Hydrogen app itself (not the workspace tooling) updates on Linux: the
restart-to-update banner, the .deb/.rpm/AppImage install with sudo or the password
prompt, and the consent-based AI path through /updater. Use when asked is there a
Hydrogen update, update Hydrogen, what version of Hydrogen am I on, or relaunch to update.
---
# 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)
```bash
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).