# Adom Bridge and Hydrogen

Adom Bridge (Adom Bridge) is a full product on its own: a standalone tray app that lets
AI assistants and remote sessions drive your Windows machine. Hydrogen
(Hydrogen) is a sibling app that bundles Adom Bridge inside its own installer and runs it in
"embedded" mode. This page explains what that relationship looks like from your
chair: what you see, what happens when Hydrogen closes or crashes, and who is in
charge of what.

![The vivid Hydrogen Embedded taskbar tile](taskbar-embedded.png)

## How Hydrogen runs Adom Bridge

Hydrogen's installer carries the signed Adom Bridge installer and silent-installs it to the
normal location (`%LOCALAPPDATA%\Adom Bridge`). At runtime Hydrogen launches Adom Bridge with
the `--embedded` and `--start-hidden` flags and connects it to Hydrogen's own relay.
From that point Hydrogen owns the user-facing surface: the window you interact with
is Hydrogen's, and Adom Bridge works quietly underneath it.

Adom Bridge keeps doing everything it normally does while embedded: serving its local
API, running bridges, connecting to relays. Embedded is a display state, not a
different program.

## What you see while embedded

- **No separate Adom Bridge window or tray icon.** Adom Bridge hides both so that Hydrogen reads as
  the one app. Adom Bridge is still running and serving.
- **The taskbar tile changes.** Adom Bridge's window identity flips from the muted
  "Adom Bridge" tile to a vivid teal tile named "Adom Bridge Hydrogen Embedded".
  The swap happens in about a second, with no restart. The tile is the
  at-a-glance signal of which mode Adom Bridge is in.
- **A locked connection row.** In Adom Bridge's Connections list, the relay entry Hydrogen
  created is marked "Managed by Hydrogen". You cannot edit, disconnect, or remove it
  while embedded, because doing so would break the embedded session. Adom Bridge's
  backend refuses those changes everywhere (including remote commands), not
  just in the UI. The entry is temporary: it is re-added each time Hydrogen launches
  Adom Bridge and goes away when Adom Bridge returns to standalone.

## When Hydrogen closes or crashes

Adom Bridge is designed to stay up. This is deliberate: Adom Bridge is the recovery channel for
the machine it runs on. As long as Adom Bridge is alive, a remote agent can read a log,
check what is installed, relaunch something, or roll back a bad update. If Adom Bridge
exited whenever Hydrogen exited, one bad Hydrogen exit would leave the machine unreachable
until someone physically walked to it.

So:

- **Hydrogen closes normally.** Hydrogen tells Adom Bridge it is releasing it, and Adom Bridge reverts to
  standalone on the spot: the tray icon comes back, the taskbar tile returns
  to the muted standalone look, and Adom Bridge's relay connections are preserved.
- **Hydrogen crashes or is killed.** Adom Bridge notices on its own (it probes Hydrogen every 10
  seconds and waits for three consecutive misses, about 30 seconds, so a quick
  Hydrogen restart does not bounce it) and then reverts to standalone the same way.
  Your machine stays reachable.
- **The only thing that exits Adom Bridge is an explicit shutdown**: the
  `desktop_shutdown` command, or you closing Adom Bridge yourself. There is a launch
  flag (`--exit-when-hd-exits`) that would make Adom Bridge exit alongside Hydrogen, but Hydrogen
  does not pass it, and there is no setting for it. In practice Adom Bridge always
  survives its parent.

One caveat: because Adom Bridge runs as Hydrogen's child process, an operating-system level
"kill the whole process tree" takes Adom Bridge down with Hydrogen instantly. That is the OS
at work, not Adom Bridge's behavior, and it is rare in normal use.

## Updates while embedded

Adom Bridge updates itself even when embedded, but the timing is shared:

- **Adom Bridge stages.** Adom Bridge checks for new versions, downloads the installer, and
  verifies its SHA-256, so a verified update sits ready on disk with no
  network needed to apply it.
- **Hydrogen triggers.** Hydrogen decides the safe moment and tells Adom Bridge to apply the staged
  update. Embedded Adom Bridge never restarts itself for an ordinary update; Hydrogen owns
  the restart timing so it does not interrupt your work.

When Adom Bridge is standalone, it handles both halves itself according to your update
preference (prompt, auto, or off).

## Permissions while embedded

When a remote AI session asks Adom Bridge to run something sensitive (a shell command,
a script, a file write), someone has to approve it. Embedded, that someone
sees the prompt in Hydrogen:

- Hydrogen tells Adom Bridge at startup whether commands should be auto-approved. Unless you
  have opted in to auto-approval, Adom Bridge forwards each sensitive request to Hydrogen,
  and Hydrogen shows the approval prompt. Adom Bridge shows no dialog of its own, so you are
  never confused by a window from an app you did not think you were running.
- Your choices in Hydrogen's prompt (allow once, allow for 1 or 24 hours, bypass
  while running, or deny) are applied by Adom Bridge exactly as decided.
- If Hydrogen is ever unreachable at the moment of a request, Adom Bridge falls back to its
  own approval dialog rather than silently approving or silently blocking.

Only remote (cloud) callers are gated this way. Local software on your own
machine, including Hydrogen itself, is trusted the way any installed app is.

## Standalone is the full product

Nothing above is a limitation of Adom Bridge. Installed on its own, Adom Bridge is the complete
experience: its own window, tray icon, connections panel, bridges sidebar,
approval prompts, and self-updates. Embedding changes who draws the window and
who picks the update moment; it does not change what Adom Bridge can do.