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-key-values description: >- The user's cloud key-value store (Carbon KV): what the hydrogen.* and bridge.* keys mean, how to read and write them, and the ownership and no-secrets rules. Use before writing a key, or when asked about my cloud settings, kv pairs, hydrogen.runtime or the key-values viewer.
Cloud key-values: the user's Adom-account KV store
Every Adom user has a small key-value store attached to their account (10MB). It syncs to every machine and container they sign in on, which makes it the shared memory between Hydrogen, Adom Bridge, and you: preferences live here, and running apps publish their live addresses here so they can be discovered from anywhere.
Reading and writing
- Read:
GET https://carbon.adom.inc/userthenbody.hydrogen_preferences.settingsis the flat map. Auth is either the session token (Cookie: session_token=<tok>) or the workspace API key (Authorization: Bearer $(cat /var/run/adom/api-key)). - Write:
PATCH https://carbon.adom.inc/user/hydrogen/settingswith body{"key": "<dotted.key>", "value": <scalar>}, same auth. Anullvalue removes the key. - From inside Hydrogen's UI surfaces, the control API relays for you:
POST /auth/proxywith{"path": "/user", "method": "GET"}(seehydrogen-api).
Conventions (follow these exactly)
- Dotted lowercase keys, brand-name prefix. Each app owns its prefix:
hydrogen.*(this app),bridge.*(Adom Bridge). Never write into another app's prefix.desktop.*keys are pre-rename legacy (the Adom-Desktop era); Hydrogen still READS them as a fallback but only ever WRITEShydrogen.*. - Scalar values only. Structured data goes in as a JSON string.
- User-visible. The profile menu's "Your cloud key-values" dialog shows every entry, pretty-printed. Keep values compact and self-explanatory.
- NEVER a secret. No tokens, no passwords, no credentials, ever.
- Modify with intent. You MAY change a
hydrogen.*preference when the user asks (e.g. sethydrogen.editor_font_size), but prefer the app's own settings surface when one exists; a raw PATCH bypasses the app's validation and mirrors. For examplehydrogen.launch_on_bootonly writes the autostart file through Settings. - SCOPE BY MACHINE OR BY ACCOUNT — decide before you write (the
multi-computer rule). The store is account-wide: every machine the user
runs Hydrogen on reads and writes the SAME map, so a key holding
per-machine state under a plain name gets clobbered by whichever machine
wrote last. Three classes, three homes:
- Account-level preferences (font size, color scheme, nav collapsed):
plain
hydrogen.<name>. Shared across machines on purpose — that's settings sync, not clobbering. - Per-machine state (live ports, runtime identity, anything two
machines would disagree about): the key MUST embed the sanitized
machine name —
hydrogen.runtime.<machine>,bridge.container.<id>. Each machine owns its own key; nothing fights. - Machine-local settings (launch-on-boot, the close button, workspace shutdown on
quit, ab window behavior): never in the cloud at all. Hydrogen keeps these on this
computer (per-machine localStorage and
~/.config/hydrogen-desktop/setup-flags.json) so one machine's choice can't leak to another. Litmus test before writing any new key: "if the user ran two computers, should they see the same value?" Yes → plain key. No → machine-suffixed key, or local storage. Two machines with the same computer name would share a runtime key; the value'sinstance_id/install_path/tsfields let a reader detect that and trust the freshest writer.
- Account-level preferences (font size, color scheme, nav collapsed):
plain
The keys you'll meet
| Key | Owner | What it is |
|---|---|---|
hydrogen.editor_font_size, hydrogen.color_scheme, hydrogen.wake_heal, ... |
Hydrogen | The Settings dialog's preference tree. |
hydrogen.runtime.<machine> |
Hydrogen | Live runtime identity, published at launch + every 4h: a JSON string {host, control, proxy, cdp, code_server, instance_id, pid, install_path, version, ts}. <machine> is the lowercase sanitized computer name. |
bridge.container.<id> |
Adom Bridge | A container connection ab dials (may appear as legacy desktop.container.<id> until ab's rename ships). |
bridge.runtime.<machine> |
Adom Bridge | ab's live runtime identity, also the Adom Mesh directory record (node id, relay, version). |
On Linux the cdp port in hydrogen.runtime.* has nothing listening (WebKitGTK has no
DevTools protocol).
Using a runtime entry (discovery)
hydrogen.runtime.<machine> lets you find a running Hydrogen from a cloud
container or another machine with no port scanning. Rules:
tsis unix seconds; older than ~5h (one missed heartbeat plus slack) means that instance is probably gone.- A live port is NOT identity: hit
GET /buildinfoon the advertised control port and matchinstance_idbefore trusting it. Zombies from uninstalled copies answering/healthare a real observed failure.
The viewer
Profile menu (avatar, top-right) → Your cloud key-values: read-only list
with filter, per-row copy, and expand for long values; refreshes from Carbon
on open. AI-drivable via the profile.keyvalues UI action.
Related skills
hydrogen-ports: the full discovery ladder these runtime entries sit in.hydrogen-settings: the Settings dialog that owns the preference keys.hydrogen-api: the control API and auth proxy.
---
name: hydrogen-key-values
description: >-
The user's cloud key-value store (Carbon KV): what the hydrogen.* and bridge.* keys
mean, how to read and write them, and the ownership and no-secrets rules. Use before
writing a key, or when asked about my cloud settings, kv pairs, hydrogen.runtime or the
key-values viewer.
---
# Cloud key-values: the user's Adom-account KV store
Every Adom user has a small key-value store attached to their account (10MB).
It syncs to every machine and container they sign in on, which makes it the
shared memory between Hydrogen, Adom Bridge, and you: preferences live here,
and running apps publish their live addresses here so they can be discovered
from anywhere.
## Reading and writing
- Read: `GET https://carbon.adom.inc/user` then
`body.hydrogen_preferences.settings` is the flat map. Auth is either the
session token (`Cookie: session_token=<tok>`) or the workspace API key
(`Authorization: Bearer $(cat /var/run/adom/api-key)`).
- Write: `PATCH https://carbon.adom.inc/user/hydrogen/settings` with body
`{"key": "<dotted.key>", "value": <scalar>}`, same auth. A `null` value
removes the key.
- From inside Hydrogen's UI surfaces, the control API relays for you:
`POST /auth/proxy` with `{"path": "/user", "method": "GET"}` (see
`hydrogen-api`).
## Conventions (follow these exactly)
1. **Dotted lowercase keys, brand-name prefix.** Each app owns its prefix:
`hydrogen.*` (this app), `bridge.*` (Adom Bridge). Never write into
another app's prefix. `desktop.*` keys are pre-rename legacy (the
Adom-Desktop era); Hydrogen still READS them as a fallback but only ever
WRITES `hydrogen.*`.
2. **Scalar values only.** Structured data goes in as a JSON *string*.
3. **User-visible.** The profile menu's "Your cloud key-values" dialog shows
every entry, pretty-printed. Keep values compact and self-explanatory.
4. **NEVER a secret.** No tokens, no passwords, no credentials, ever.
5. **Modify with intent.** You MAY change a `hydrogen.*` preference when the
user asks (e.g. set `hydrogen.editor_font_size`), but prefer the app's own
settings surface when one exists; a raw PATCH bypasses the app's
validation and mirrors.
For example `hydrogen.launch_on_boot` only writes the autostart file through Settings.
6. **SCOPE BY MACHINE OR BY ACCOUNT — decide before you write (the
multi-computer rule).** The store is account-wide: every machine the user
runs Hydrogen on reads and writes the SAME map, so a key holding
per-machine state under a plain name gets clobbered by whichever machine
wrote last. Three classes, three homes:
- **Account-level preferences** (font size, color scheme, nav collapsed):
plain `hydrogen.<name>`. Shared across machines *on purpose* — that's
settings sync, not clobbering.
- **Per-machine state** (live ports, runtime identity, anything two
machines would disagree about): the key MUST embed the sanitized
machine name — `hydrogen.runtime.<machine>`, `bridge.container.<id>`.
Each machine owns its own key; nothing fights.
- **Machine-local settings** (launch-on-boot, the close button, workspace shutdown on
quit, ab window behavior): never in the cloud at all. Hydrogen keeps these on this
computer (per-machine localStorage and `~/.config/hydrogen-desktop/setup-flags.json`)
so one machine's choice can't leak to another.
Litmus test before writing any new key: "if the user ran two computers,
should they see the same value?" Yes → plain key. No → machine-suffixed
key, or local storage. Two machines with the same computer name would
share a runtime key; the value's `instance_id`/`install_path`/`ts` fields
let a reader detect that and trust the freshest writer.
## The keys you'll meet
| Key | Owner | What it is |
|---|---|---|
| `hydrogen.editor_font_size`, `hydrogen.color_scheme`, `hydrogen.wake_heal`, ... | Hydrogen | The Settings dialog's preference tree. |
| `hydrogen.runtime.<machine>` | Hydrogen | Live runtime identity, published at launch + every 4h: a JSON string `{host, control, proxy, cdp, code_server, instance_id, pid, install_path, version, ts}`. `<machine>` is the lowercase sanitized computer name. |
| `bridge.container.<id>` | Adom Bridge | A container connection ab dials (may appear as legacy `desktop.container.<id>` until ab's rename ships). |
| `bridge.runtime.<machine>` | Adom Bridge | ab's live runtime identity, also the Adom Mesh directory record (node id, relay, version). |
On Linux the `cdp` port in `hydrogen.runtime.*` has nothing listening (WebKitGTK has no
DevTools protocol).
## Using a runtime entry (discovery)
`hydrogen.runtime.<machine>` lets you find a running Hydrogen from a cloud
container or another machine with no port scanning. Rules:
- `ts` is unix seconds; older than ~5h (one missed heartbeat plus slack)
means that instance is probably gone.
- A live port is NOT identity: hit `GET /buildinfo` on the advertised control
port and match `instance_id` before trusting it. Zombies from uninstalled
copies answering `/health` are a real observed failure.
## The viewer
Profile menu (avatar, top-right) → **Your cloud key-values**: read-only list
with filter, per-row copy, and expand for long values; refreshes from Carbon
on open. AI-drivable via the `profile.keyvalues` UI action.
## Related skills
- `hydrogen-ports`: the full discovery ladder these runtime entries sit in.
- `hydrogen-settings`: the Settings dialog that owns the preference keys.
- `hydrogen-api`: the control API and auth proxy.