main
John Lauer Publish 0.1.0 d8a45ab

Hydrogen: opening a URL (Linux)

When a user says "open the ti.com website" (or any URL), Hydrogen has several paths and a Browser Picker — but don't hand the user the picker to decide. Pick the best destination for them by use-case and open it directly, then offer the alternatives in one line. The right path depends on what they're doing — look at it, have you drive it, keep it as a tab, or just read it. See "Decide for the user — DON'T hand them the picker" below for the rule.

The governing rule: background by default

When YOU (the AI) open a browser window, ask for the background. To foreground, pass foregroundReason:"<why>" (logged). Legit reasons: a sign-in or consent page the user must click now, or the user said "show me now". Omit it and the open is a background open.

On Linux Hydrogen cannot push a newly opened native browser window behind its own window: the desktop's window manager decides whether it takes focus. So prefer in-Hydrogen destinations (wv, hbw) or a headless fetch when you only need to look, and tell the user when you open their browser.

The six ways

# Option Best when… What the user sees AI drives it?
1 Hydrogen webview tab (aka wv) the user wants the site inside Hydrogen, next to their work, and to keep it around a panel/tab in the Hydrogen workspace partly (reload/route)
2 Hydrogen Browser Window a quick popout window owned by Hydrogen, not a full browser a standalone Hydrogen-owned window no
3 Pup (Puppeteer Chrome) you need to act on the page: screenshot, click, scrape, fill a form, verify a pup window on a machine that runs Adom Bridge (Hydrogen does not set it up on Linux) yes, fully
4 Native desktop browser real logins/sessions, downloads, "just open it for me", auth flows their own Firefox, Chrome, Chromium... profile no
5 Browser Picker you're not sure, or it's an auth/OAuth link — let the user choose (5s auto-default) a chooser dialog n/a (routes to one of the above)
6 curl / fetch (headless) you only need the content, not to show anything (read a datasheet, scrape JSON) nothing — runs in the workspace yes

"wv" = webview — the shortcut (spread it like pup)

wv is the short alias for "webview" — recognize it everywhere a user might say "webview" (open it in wv, wv tab, shot the wv, wv mode). Treat wv and webview as identical.

Help it catch on: the first time in a session a user types the long form "webview", open it as normal and add a one-line nudge — "(btw you can just say wv — fewer keystrokes)." Say it once, not every time (don't nag). This is exactly how puppeteer → pup became universal among Adom folks; webview → wv is the same play. (If the user already says wv, they got the memo — skip the nudge.)

Never use VS Code's Simple Browser for "show me X in webview". The only correct destination is a Hydrogen webview tab (hydrogen-webview skill).

How you invoke each

All of these run from inside the Hydrogen workspace. The control API base URL is the live value in ~/.adom/hydrogen-control-url — http://127.0.0.1:<dynamic> (the workspace shares loopback with the host; the port is dynamic per launch). Read it with BASE="$(cat ~/.adom/hydrogen-control-url)" then hit "$BASE/<endpoint>". On Linux the workspace machine shares the host's network, so 127.0.0.1 is the same on both sides.

1. Webview tab (wv) — add a web-view tab pointed at the URL (adom-workspace-control, or adom-cli hydrogen webview open-or-refresh --name <X> --url <url> --panel-id <id>). Good for "keep this open while we work." ⚠️ open-or-refresh needs --panel-id to CREATE a new tab — without it you get "Tab 'X' not found and --panel-id not provided" (verified live 2026-06-14; get a panel id from adom-cli hydrogen workspace get). Re-running with the same --name once it exists just navigates/refreshes (no panel-id needed). Same adom-cli on web-Hydrogen and Hydrogen — the consistent surface.

2 / 4 / 5. Through the Browser Picker — the single unifying entry point. POST the URL and Hydrogen routes it (auto-picking a sensible default after a 5-second countdown, or showing the chooser):

BASE="$(cat ~/.adom/hydrogen-control-url)"   # http://127.0.0.1:<dynamic>

# Auto-route (picker picks the best default in 5s — hands-free)
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"url":"https://www.ti.com"}' \
  "$BASE/open-url"

# Force the chooser dialog (no auto-timer — make the user pick)
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"url":"https://www.ti.com","force":true}' \
  "$BASE/open-url"

# Route through the picker with the FRESH-WINDOW toggle pre-checked (the picked
# native browser opens in a new window instead of a tab):
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"url":"https://claude.ai/","fresh":true,"force":true}' \
  "$BASE/open-url"
# ...or bypass the picker and open directly+fresh in a specific browser:
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"url":"https://claude.ai/","browser":"firefox","profileDir":"Default","fresh":true}' \
  "$BASE/open-in-profile"

If /open-url replies with a timeout, check GET $BASE/browser-picker/last-open ({destination, url, fresh, ts}) before calling it a failure.

Sign-ins open in the system browser. On Linux, AI sign-ins (/open-url with signin:true, sent by Manage AIs) skip the picker and open in the system browser in the foreground. The picker also treats known sign-in hosts (auth.openai.com, accounts.google.com, Kimi, /oauth/authorize pages, device-code pages) as sign-ins and lists native browsers first: those pages refuse to load inside Hydrogen. For any sign-in the picker defaults to the OS default browser.

Fresh window ("fresh":true): the native-browser path (#4) opens the URL in a new window (--new-window / -new-window) instead of a tab in the running browser. Whether that window takes focus is up to the desktop's window manager. The Browser Picker defaults the "Open in a fresh window" toggle ON for auth URLs. On /open-url, fresh pre-seeds that toggle (add direct:true to skip the picker); /open-in-profile opens fresh directly.

4. Native browser in a profile (Hydrogen Native Open).

curl -s "$BASE/browser-profiles"   # [{browser, dir, name, email, isDefault}]
  • Always pass a profileDir from /browser-profiles so the window carries the user's login.
  • Browsers detected on Linux: Firefox, Chrome, Chromium, Edge, Brave, Vivaldi, Opera, installed natively, as a snap or as a Flatpak. A Firefox profile with dir Default is that install's default (opens in the running Firefox); any other is opened with -P <name>.
  • The answer's method names the program and profile. Read it before claiming success.

Pup. Pup windows come from Adom Bridge's Puppeteer bridge. adom-bridge pup_* reaches a machine that runs Adom Bridge: this computer once Hydrogen has installed it (when a Linux build is published for the user's account), or the user's other machine through the Adom mesh. If no bridge answers, use wv or hbw for looking and curl for reading. See hydrogen-pup.

6. Headless content — if you only need to read the page, skip the browser entirely:

curl -sL https://www.ti.com/...   # or fetch from your own code

They open with the desktop's default app for that scheme. When none is set, Hydrogen copies the address to the clipboard and says so in a toast.

Decide for the user — DON'T hand them the picker

Default behavior: pick the destination by use-case and open it DIRECTLY (bypass the picker), then give a one-line heads-up + easy undo. Do NOT fire a plain POST /open-url {url} and let the picker's generic 5-second auto-default decide — that default is luck-of-the-draw and often wrong for the use-case (a vendor-login site could land in Pup where the user has no login). Users don't want to make this choice; make the smart one for them. (Mechanics: /open-in-profile opens a specific native browser+profile directly; /open-url {direct:true} bypasses the picker; Pup and webview-tab are direct calls. Reserve the picker only as below.)

Use case Open it in How (bypass the picker)
Login-likely site — vendor/account/portal/cart: TI, Mouser, DigiKey, any "my…"/sign-in the user's native browser + WORK profile (their saved login/cookies live there) GET /browser-profiles → find the work profile (non-gmail) → POST /open-in-profile {url, browser, profileDir, fresh:true}
Building/testing their own app, or you need to drive/screenshot/scrape the page Pup (AI-drivable, needs Adom Bridge, see above) adom-bridge pup_*
Glance at content alongside their work Hydrogen webview tab adom-workspace-control add web-view tab
A quick popout owned by Hydrogen Hydrogen Browser Window (hbw) POST /hbw/open
You only need the content headless curl -sL <url>
Genuinely ambiguous, OR an OAuth/sign-in the user must complete themselves let them choose POST /open-url {url, force:true} — the one time the picker is right

Then say it in one line, with the undo: "Opened TI in your Chrome work profile (where your TI login lives) — say the word for a tab here, Pup, or a different profile." Decide, act, offer alternatives — don't ask first.

Example — "open the texas instruments website" (login-likely → native work profile):

BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s "$BASE/browser-profiles"     # pick the work profile (non-gmail email)
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"url":"https://www.ti.com","browser":"chrome","profileDir":"<work profileDir>"}' \
  "$BASE/open-in-profile"

Govern routing policy — the picker is now a true FALLBACK (Hydrogen prefs API)

The picker's per-domain memory is a first-class API (Hydrogen app behavior), so the AI OWNS URL routing — the picker only pops for a domain with no stored policy AND no direct call. Use this to set policy the user would otherwise click through the Manager for ("always open DigiKey in my work profile", "stop auto-opening X in Edge").

BASE="$(cat ~/.adom/hydrogen-control-url)"
# READ the policy map
curl -s "$BASE/browser-picker/prefs"
#   → {ok, prefs:{domains:{"<host>":{destination,label}, …}}}
# SET / override one domain
curl -s -X PUT "$BASE/browser-picker/prefs" -H 'Content-Type: application/json' \
  -d '{"domain":"digikey.com","destination":"browser:edge:Default","label":"Edge — Default"}'
# FORGET one domain  (e.g. "stop auto-opening X in Edge")
curl -s -X DELETE "$BASE/browser-picker/prefs/digikey.com"
# CLEAR all
curl -s -X DELETE "$BASE/browser-picker/prefs"
  • Stored value = {destination, label} — NOT profileDir/fresh.
  • destination is an ID:
    • internal: hydrogen-tab (a webview/wv tab) · webview-window · pup-window
    • native: browser:<browser>:<dir> — e.g. browser:edge:Default, browser:chrome:Profile 1. The profile dir is encoded in the ID (no separate field).
  • Discover valid native IDs via GET $BASE/browser-profiles (maps each detected profile → its browser+dir); the 3 internal IDs are fixed above.
  • fresh is NOT stored in prefs — it's a per-OPEN flag (/open-url {fresh:…} / /open-in-profile {fresh:…}). Don't try to persist it here.
  • Writes hit the live Manager UI immediately (the backend writes hydrogen-url-routing-prefs localStorage + dispatches hydrogen-url-routing-prefs-changed; an open Browser Picker Manager re-reads at once, and re-reads on open anyway).

Net: for a one-off open, decide and call the direct endpoint (/open-in-profile, /open-url {direct:true}, or a wv/pup call). For a standing preference, PUT the domain's policy so even user-initiated link clicks route there silently. The picker is now only a fallback for the genuinely-undecided.

  • hydrogen-browser-picker — the interception layers + picker dialog behind #2/#4/#5
  • hydrogen-pup — driving Pup browser windows (#3): navigate, screenshot, eval, reload
  • adom-workspace-control — adding/managing Hydrogen webview tabs (#1)
  • hydrogen-runtime-mode — none of this changes across workspace runtimes