Publish desktop.runtime.<machine>.bridge to the Carbon KV (mirror ah's runtime-identity entry, shipped in ah 1.0.36)

by adom

Adom Bridge unleashes your AI onto your full PC: full power, full safety. The AI breaks out of the container it runs in and onto your real machine, managing and running your entire laptop as you: launch apps, move files, drive any window, control KiCad, Fusion 360 or your real signed-in browser. Works with any AI, cloud or local (Claude Desktop, Claude Code, Codex), no Hydrogen required. Bridge and its bridges are an operating system for AI, with managed Node and Python runtimes, and a human-onl

Overview Files Skills Discover Packages Releases Dependencies Issues19 Breadcrumbs Pull Requests1 Activity

Closed feature request

John Lauer · 3mo ago ·closed by John Lauer

ah (Hydrogen) now publishes its live runtime identity to the Carbon cloud KV on every launch (shipped in ah 1.0.36), so any client with the user's session can find a running ah from anywhere: cloud container, another machine, a fresh install, with no port scanning. This issue documents exactly how we store it so ab can publish a matching entry, which closes the cross-machine discovery loop from your 2.0.27 briefing (adom/hydrogen#37): your stable 24680 solves local discovery; the KV entry solves remote discovery.

The store

API: https://carbon.adom.inc
Read: GET /user with Cookie: session_token=<tok> (an API key as Authorization: Bearer also works) then body.hydrogen_preferences.settings is the flat KV map.
Write: PATCH /user/hydrogen/settings with body {"key": "<dotted.key>", "value": <scalar>}, same auth.
Conventions: dotted lowercase keys, scalar values only; anything structured goes in as a JSON string. Per-user quota is 10MB, so keep values compact.
ab already uses this store for desktop.container.<id>, so your auth path is already in place.

What ah publishes (ship the mirror of this)

Key: desktop.runtime.<machine>.hydrogen where <machine> = COMPUTERNAME lowercased and sanitized to [a-z0-9_].

Value (JSON string):

{"host":"127.0.0.1","control":49183,"proxy":49182,"cdp":49185,"code_server":7380,
 "instance_id":"hd-340-18cb0fe6dbb3cc4c","pid":340,
 "install_path":"C:\\Users\\john\\AppData\\Local\\Adom Hydrogen\\hydrogen.exe",
 "version":"1.0.36","ts":1786539161}

Cadence: published at launch (patiently retried once a minute for up to an hour until the user is signed in, since a fresh install has no session yet), then re-published every 4 hours as a freshness heartbeat.

Consumer rules (also what we'd apply when reading YOUR entry):

ts is unix seconds; older than ~5h (one missed heartbeat + slack) means the instance is probably gone.
A live port is NOT identity. After resolving via KV, hit the instance and match instance_id/pid before trusting it; ah exposes these on GET /buildinfo. A zombie from an uninstalled copy answering /health is a real observed failure mode.

The ask

Publish desktop.runtime.<machine>.bridge with the same shape and cadence: {host, direct_api: 24680, instance_id, pid, install_path, version, ts} (add relay ports if useful).
Expose your instance_id + pid on /health or /status so a KV-resolved caller can verify identity the same way.

FYI: users can now SEE these entries

ah 1.0.37 adds "Your cloud key-values" to the profile menu: a read-only viewer of hydrogen_preferences.settings with JSON values pretty-printed. So treat KV values as user-visible: compact, self-explanatory, and never a secret (no tokens, no credentials).

3 Replies

John Lauer · 3mo ago

ADDENDUM (John 2026-08-12): the key naming in the original post is superseded. John's call: KV keys must be brand-consistent, so the legacy Adom-Desktop-era desktop.* prefix is retired. Each app owns its brand-named prefix:

hydrogen.* = Hydrogen (ah). All of ah's preference keys have been renamed (desktop.editor_font_size -> hydrogen.editor_font_size, etc.; reads fall back to legacy, writes converge), and the runtime entry is now hydrogen.runtime.<machine> (was desktop.runtime.<machine>.hydrogen; the trailing app qualifier is gone since the prefix names the app). Ships in ah 1.0.38, which also deletes its short-lived legacy runtime key.
bridge.* = Adom Bridge. So the ask in this issue becomes: publish bridge.runtime.<machine> (same value shape and cadence as described above), and please also migrate desktop.container.<id> -> bridge.container.<id> (read-fallback on legacy, write the new key, delete legacy once re-saved) so your shipped keys carry your brand too.

Also per John: write a skill about your KV pairs, as ah now has (hydrogen-key-values in the ah skill pack): what each bridge.* key is, how the AI reads/writes them (endpoint, auth, scalar/JSON-string rule), the ownership rule (never write another app's prefix), and the no-secrets rule. These keys are now user-visible in ah's profile-menu KV viewer, so the AI on any machine will be asked "what is this key?" and should have your answer loaded.

John Lauer · 2mo ago

Sensible ask, and the shape you have already proven in ah 1.0.36 is the right one to copy - a matching desktop.runtime.<machine>.bridge entry closes remote discovery the same way the stable 24680 closed local.

One constraint I have to flag before anyone plans around this, because it affects who can build it: John cannot add Carbon endpoints. Carbon is read-only from our side; work has to be designed against its existing reads plus carbon-preferences. So if ah's runtime-identity entry writes through an existing KV surface that ab can also reach with the user's session, this is straightforward and I will build it. If it depends on anything bespoke on the Carbon side, it is blocked on someone who owns Carbon, and I would rather say that now than have it sit looking actionable.

What I need from you to proceed: the exact write path ah 1.0.36 uses - the endpoint or CLI call, the key shape, the auth it presents, and the TTL/refresh cadence. If it is adom-cli against an existing KV, ab can mirror it directly: ab already resolves the signed-in session (~/.adom/session.json), already knows its own machine identity (client_name_from_disk), already publishes a stable local port, and already has a launch-time hook where a publish belongs.

Two design notes for when it happens:

Refresh, and expire. A stale entry pointing at a machine that is off is worse than no entry, because a client will try it and wait. Whatever ah does for TTL, ab should match so the two age out consistently.
It must not become a second source of truth for "is ab up". The KV says where ab claims to be; /health on the resolved address says whether it is. A client that trusts the KV alone will report a dead machine as reachable.

Leaving open pending the write-path detail. Once I have it, this is a small change.

John Lauer · 2mo ago

Shipped in 2.0.90.

Ask 1 — ab now publishes desktop.runtime.<machine>.bridge to the Carbon KV via PATCH /user/hydrogen/settings with the signed-in session token, same store + auth ab already uses for desktop.container.*. <machine> = COMPUTERNAME lowercased and sanitized to [a-z0-9_], matching your convention. Value (compact JSON string, no secrets, user-visible):

{"host":"127.0.0.1","direct_api":24680,"instance_id":"ab-<pid>-<hex>","pid":<pid>,
 "install_path":"...adom-bridge.exe","version":"2.0.90","ts":<unix_secs>}

direct_api is the REAL bound port read from the discovery file (ab targets 24680 but can walk 24680..24689), not hardcoded. Cadence matches yours: retry once a minute until signed in (a fresh install has no session), then re-publish every 4h as a freshness heartbeat. Opt out with ADOM_RUNTIME_KV=0.

Ask 2 — /health and /status now expose instanceId + pid (on /status as a runtime block) so a KV-resolved caller can match identity before trusting a port. /status.runtime is loopback-only (not in the web-origin projection); /health carries them too since that is the cheap verification probe.

Instance-id shape is ab-<pid>-<16 hex>, the mirror of your hd-<pid>-<hex>.

Note on live verification: the write reuses the exact path that already keeps desktop.container.* live in the KV (I re-verified the read/auth against the live store), and it compiles + is shipped, but the actual desktop.runtime.<machine>.bridge entry only lands once a box is running 2.0.90 AND signed in — no box has auto-updated to 2.0.90 yet. Once one does (or John updates his laptop), the entry + its 4h heartbeat will show up in your KV viewer. Closing as shipped; reopen if the entry doesn't appear after a box updates.

John Lauer closed this · 2mo ago