--- name: adom-desktop-auth description: "Sign in to Adom Bridge and connect a cloud container to the user's Mac: the Connections panel 'Sign in to Adom' browser flow, the shared macOS keychain session (one sign-in serves Bridge and Adom Hydrogen), auto-discover servers from the user's Adom Cloud profile (zero JSON paste), register_container from a cloud container, the one-command setup_desktop flow, the cloud key-value config keys (desktop.container.*), the paste-JSON fallback, and sign-out. Trigger words: sign in to Adom Bridge, connect container to desktop, register_container, setup_desktop, auto-discover servers, connect my desktop, server JSON, cloud config, sign out, keychain session." --- # Adom Bridge: sign-in, auth, and cloud configuration Adom Bridge (formerly Adom Desktop) runs on the user's Mac. You (the AI) usually run in a cloud container. This skill covers how the two get connected through the user's Adom account: the modern, zero-paste path, plus the fallbacks. ## The short version 1. From the cloud container, run `adom-desktop setup_desktop`. It returns a ready-to-run `register_command`. 2. Run that `register_command` (it is `register_container` with the name + URL filled in). This writes the connection into the USER'S ADOM ACCOUNT. 3. The user installs Adom Bridge on their Mac and signs in with their Adom account. The container appears in their Connections list and auto-connects. No JSON paste at all. 4. Keep the relay running on your side: `adom-desktop serve --supervise`. Verify with `adom-desktop targets`. ## How the user signs in (what happens inside Bridge) The user clicks **"Sign in to Adom"**: a prominent CTA in the Connections panel when they are signed out (there is also a sign-in link in the footer). Bridge runs as a menu-bar agent, so a sign-in that needs the window summons it automatically. Bridge then: - Creates an auth intent with Carbon (the Adom auth backend) and opens the returned `auth_url` in the user's **default browser**. - The user approves on the Carbon intent screen in the browser. - Bridge polls the intent every 2 seconds (up to 15 minutes), validates the session via `GET /user`, and persists it. On a fresh, signed-out, standalone launch, Bridge shows a 5-second auto-login countdown ("Logging you into Adom in 5, 4, 3, 2, 1", with Cancel) and then opens the sign-in link automatically. If the browser flow fails or stalls, Bridge shows an in-window banner with a one-click **Retry** (the 'failed' copy reminds the user to pick their Adom account in the browser). The sign-in button stays retryable: a stuck poll never dead-ends the UI. ## One sign-in, shared keychain The session is stored as a **shared macOS keychain item** that serves BOTH Adom Bridge and Adom Hydrogen: one Adom sign-in covers the whole family on that Mac, and the session survives an uninstall/reinstall of either app. The on-disk cache at `~/.adom/session.json` is just that, a cache: when it is missing, Bridge rebuilds it from the keychain at launch. Sign-out deletes the keychain item everywhere, including iCloud-synced copies. ## What sign-in unlocks: auto-discovered servers, zero JSON Once signed in, Bridge pulls the user's registered containers from their Adom Cloud profile (the `desktop.container.*` keys in their cloud preferences) and merges them into the local Connections list: - **Immediately after an interactive sign-in** (`sync_cloud_servers_now` runs as part of completing the flow, then connects the new entries right away: the LED goes green in seconds, not after a 30s supervisor tick). - **At every boot** while a session is present (the boot-time cloud sync). So the user never pastes server JSON: register the container from your side, have them sign in, and the connection appears and auto-connects. ## register_container: register THIS container in the user's account Run this on the cloud container (imperative: you do it, not the user): ```bash adom-desktop register_container '{"name":"my-container","url":"wss://.adom.cloud/proxy/8765/"}' ``` - `name` (required): the human-friendly label shown in Bridge's server list. - `url` (required): the public `wss://` URL the desktop will dial, typically `wss://.adom.cloud/proxy/8765/`. - Optional: `id` (defaults to a uuid v4; a caller-provided id stays stable across re-runs), `auth_token` (defaults to `adom-dev-token-2025`, what the cloud relay accepts by default), `auto_connect` (default true), `enabled` (default true). What it does: authenticates with the session token Adom infra mounts at `/var/run/adom/api-key`, then PATCHes three cloud key-value config keys in the user's carbon-preferences: - `desktop.container.`: the full server entry as a JSON string - `desktop.last_slug`: the id of this container - `desktop.enabled`: `true` Bridge's cloud-config pull reads those keys after sign-in and at boot. **Only works on Adom cloud containers.** On any other box the mounted token is absent and the verb returns `ok:false` with an error explaining that; fall back to paste-JSON (below). Other returns worth knowing: - Success: `{ok:true, id, name, url, _hint}` with the user's next steps. - **Idempotent by URL**: calling it again for a URL that is already registered reuses the existing entry (refreshes its fields) and returns `ok:true` with `was_duplicate:true` and `warning_code:"DUPLICATE_URL_NO_NEW_ENTRY_CREATED"`. URL is the natural key: call it once per container, not on every loop. The registration persists across sessions, machines, and Bridge reinstalls because it lives in the user's account, not on any one machine. - To revert: PATCH `desktop.container.` to `null` in carbon-prefs. If Bridge is already installed and signed in when you register, the user can restart Bridge (or wait: it also polls the cloud config at boot) to see the new container. ## setup_desktop: the one-command setup flow Don't hand-build the connection JSON (the number one setup mistake). Run: ```bash adom-desktop setup_desktop ``` Aliases: `setup`, `connect`, `connect_info`, `connection`, `connection_setup`, `server_json`; they all run the same thing. It auto-detects this container's public relay URL and returns: - `register_command`: the preferred path, a ready-to-run `register_container` invocation with this container's name + URL filled in. Run it. - `server_config`: the fallback JSON to paste into Bridge if `register_container` returns `ok:false`. - `installer_url` / `release_url`: where the user gets the Mac install. The one-line install is: ```bash curl -fsSL https://wiki.adom.inc/api/v1/pages/adom-bridge-macos/files/install.sh | sh ``` (Downloads the notarized dmg from the `adom/adom-bridge-macos` wiki page, sha-verified. On machines running Adom Hydrogen, Hydrogen installs Bridge automatically.) - `server_url`, `desktop_connected`, `steps[]`, `_hint`, `_next`. Either path requires the relay to be running on the container so the desktop has something to dial: ```bash adom-desktop serve --supervise ``` Then verify: ```bash adom-desktop targets adom-desktop ping ``` `ping` returning `{"echo":"pong","status":"connected"}` means the desktop is reachable. macOS (Apple Silicon) is the supported desktop platform for this build. Each container has its own relay: a new container needs its own registration; entries from previous containers won't work. ## Paste-JSON fallback (non-Adom boxes, or the user won't sign in) If `register_container` returned `ok:false`, have the user: 1. Install Adom Bridge and open it (the window is summoned from the menu-bar item). 2. Paste the `server_config` JSON from `setup_desktop` into the Connections panel's **"Paste server JSON to add"** box and press Enter. 3. The server appears and auto-connects: wait for the green dot. Use the `server_config` exactly as returned; do not hand-assemble it. ## Sign-out - In the GUI: the **Sign-out** link. It clears the session everywhere: the shared keychain item is deleted (including iCloud-synced copies), and the `~/.adom/session.json` cache is cleared. Because the keychain item is shared, sign-out signs the user out of Adom Hydrogen on that Mac too. - From the CLI/relay: `desktop_logout` does the same thing. Adom Hydrogen calls it on its own sign-out so Bridge doesn't show a stale email in its footer. ```bash adom-desktop desktop_logout ``` After sign-out, Bridge reports no signed-in identity until the user signs in again. Cloud-discovered servers stop syncing until the next sign-in. ## Related verbs - `server_add` / `server_remove` / `server_list`: programmatic server registration on the DESKTOP side (upsert by name, idempotent); persists to the same `~/.adom/config.json` the GUI uses. - `targets`: list connected desktops; `--target ` routes a verb to a specific one when several are connected.