# Adom Desktop and Hydrogen Desktop

Adom Desktop (AD) is a full product on its own: a standalone tray app that lets
AI assistants and remote sessions drive your Windows machine. Hydrogen Desktop
(Hydrogen) is a sibling app that bundles AD 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 AD

Hydrogen's installer carries the signed AD installer and silent-installs it to the
normal location (`%LOCALAPPDATA%\Adom Desktop`). At runtime Hydrogen launches AD 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 AD works quietly underneath it.

AD 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 AD window or tray icon.** AD hides both so that Hydrogen reads as
  the one app. AD is still running and serving.
- **The taskbar tile changes.** AD's window identity flips from the muted
  "Adom Desktop" tile to a vivid teal tile named "Adom Desktop Hydrogen Embedded".
  The swap happens in about a second, with no restart. The tile is the
  at-a-glance signal of which mode AD is in.
- **A locked connection row.** In AD'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. AD'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
  AD and goes away when AD returns to standalone.

## When Hydrogen closes or crashes

AD is designed to stay up. This is deliberate: AD is the recovery channel for
the machine it runs on. As long as AD is alive, a remote agent can read a log,
check what is installed, relaunch something, or roll back a bad update. If AD
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 AD it is releasing it, and AD reverts to
  standalone on the spot: the tray icon comes back, the taskbar tile returns
  to the muted standalone look, and AD's relay connections are preserved.
- **Hydrogen crashes or is killed.** AD 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 AD is an explicit shutdown**: the
  `desktop_shutdown` command, or you closing AD yourself. There is a launch
  flag (`--exit-when-hd-exits`) that would make AD exit alongside Hydrogen, but Hydrogen
  does not pass it, and there is no setting for it. In practice AD always
  survives its parent.

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

## Updates while embedded

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

- **AD stages.** AD 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 AD to apply the staged
  update. Embedded AD never restarts itself for an ordinary update; Hydrogen owns
  the restart timing so it does not interrupt your work.

When AD 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 AD 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 AD at startup whether commands should be auto-approved. Unless you
  have opted in to auto-approval, AD forwards each sensitive request to Hydrogen,
  and Hydrogen shows the approval prompt. AD 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 AD exactly as decided.
- If Hydrogen is ever unreachable at the moment of a request, AD 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 AD. Installed on its own, AD 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 AD can do.