main
John Lauer Publish 0.1.0 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/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.

  • 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.