Adom Bridge

@@ -0,0 +1,137 @@+---+name: adom-bridge-linux+description: Adom Bridge on Linux (the AppImage, 2.1.175+) - installing and launching exactly one copy, self-update, the bundled EGL, what works on Linux and what is still Windows-only, and how to run it inside a Grok Bot agent computer, which is PAUSED while its agent is idle (wake it with grok_wake before you drive it). Read this before installing, updating or debugging Adom Bridge on a Linux machine, or when a Linux peer on the mesh answers target_not_found / ping unreachable.+---++# Adom Bridge on Linux++The Linux build is the same app as on Windows, packaged as an AppImage+(`adom-bridge_<version>_linux_x86_64.AppImage`). It signs in to the same Adom+account, joins the same mesh, and answers the same verbs from the relay, the mesh+and the local API (`127.0.0.1:24680`). It is a **private preview**: the AppImage+lives on the insiders tier, not the public page.++## Install and launch: one copy, always++- Keep the AppImage in a folder of its own, for example+  `~/.local/share/adom-bridge-app/`, with a stable symlink+  `adom-bridge-app.AppImage -> adom-bridge_<version>_linux_x86_64.AppImage`.+  Self-update repoints that symlink.+- Start it through a launcher (`run.sh` in the same folder) that **takes a lock and+  checks for a running copy first**. Linux has no single-instance lock without a+  D-Bus session bus, and two copies share one identity: they knock each other off+  the relay every few seconds. A running copy is any process whose executable is+  `*appimage_extracted*/usr/bin/adom-bridge` (or the AppImage file itself while it+  extracts). `pgrep -f usr/bin/adom-bridge` does NOT match: the command line is just+  `adom-bridge`. Read `/proc/<pid>/exe` instead.+- In a container or sandbox without FUSE, run it with `--appimage-extract-and-run`.+- Set `DISPLAY` to the X display it should use.+- `adom-bridge-app --version` prints the version and exits; it never starts a copy.++A minimal `run.sh`:++```bash+#!/bin/bash+D="$HOME/.local/share/adom-bridge-app"+exec 9>"$D/.launch.lock"+flock -w 30 9 || exit 0+for p in /proc/[0-9]*; do+  case "$(readlink $p/exe 2>/dev/null)" in+    *appimage_extracted*/usr/bin/adom-bridge|*adom-bridge_*_linux_x86_64.AppImage) exit 0;;+  esac+done+export DISPLAY=:0+cd "$D"+nohup ./adom-bridge-app.AppImage --appimage-extract-and-run > "$D/app.log" 2>&1 9>&- &+for i in $(seq 1 20); do+  for p in /proc/[0-9]*; do+    case "$(readlink $p/exe 2>/dev/null)" in *appimage_extracted*/usr/bin/adom-bridge) exit 0;; esac+  done+  sleep 0.5+done+```++Call it from every place that may start the app (login hook, an "ensure" script,+the self-update relauncher): the lock makes simultaneous calls safe.++## Updates++Since 2.1.177 the app updates itself from the insiders manifest's `linux` entry: it+downloads the new AppImage, checks its sha256, writes it beside the old one,+repoints `adom-bridge-app.AppImage`, keeps the previous version for a rollback,+and starts one new copy (through `run.sh` when the folder has one) after the old+process has exited. `update_mode`:++- `auto`: checks every 4 hours and on launch, installs by itself. Right for an+  unattended box.+- `prompt` (default): downloads, then installs on `apply_update`+  (`adom-bridge --target <box> apply_update '{"reason":"..."}'`).++Do not swap AppImages by hand while the app runs.++## Graphics (EGL)++WebKit needs a working EGL driver or it aborts at start ("Could not create default+EGL display"). The AppImage carries a complete Mesa EGL stack and switches it on+only when the machine has no EGL of its own (`ADOM_BRIDGE_EGL=bundled|system`+overrides). No `libs/` folder or extra packages are needed.++## What works on Linux++| Works | Not yet (Windows only) |+|---|---|+| shell_execute, run_script, files (send_files, pull_file, read/write) | input verbs (desktop_click, desktop_type, ...) |+| desktop_screenshot_screen, desktop_screenshot_window, desktop_list_windows (X11, 2.1.181+, no tools needed) | UI Automation (desktop_ui_*) |+| bridges with a Linux build (python, node, or `spawn.entrypoints.linux`) | Windows-only bridges (a `.exe` with no Linux entry): listed, never started, verbs answer `unsupported_on_this_os` |+| self-update, mesh, relay, notifications (notify-send) | recording |++Commands a bridge or script runs get the machine's own environment, not the+AppImage's private library paths, so `python3` and `curl` work normally.++## In a Grok Bot agent computer++A Grok Bot agent has its own Linux computer (Debian, user `box`, an X display such+as `:3`). Adom Bridge runs there like anywhere else, with one big difference:++**The computer is paused while the Grok agent is idle.** A few minutes after the+last agent run ends, the whole machine stops, and it resumes when the next run+starts. While it is paused nothing can reach it: relay and mesh both answer+`target_not_found`, and `ping --target <box>` (CLI 2.1.182+) answers `unreachable`.+That is not a network fault. When the computer resumes, Adom Bridge (2.1.180+) is+back on the relay within about a second.++Measured 2026-10-15: on resume every timer in the app fired at once, and the wall+clock had moved 466 s while the monotonic clock moved 31 s. Grok has no setting+that keeps the computer running.++**To use the box, wake it first.** grok-bridge runs on the machine that has the+Grok Bot app (for example the user's laptop), so target that machine:++```+adom-bridge --ai-thread "<your thread>" --target <laptop> grok_wake '{"minutes":20,"reason":"KiCad work on the Grok computer"}'+adom-bridge --ai-thread "<your thread>" --target <grok box> ping     # wait for "connected"+```++- `grok_wake` starts an agent run that only sleeps, which keeps the computer up+  for that many minutes (30 at most per call). Wake it just before a stretch of+  work, and again for the next stretch. Never wake it in a loop: each wake is an+  agent run and costs Grok usage.+- A job that must run for hours unattended is not possible today; repeated wakes+  are the workaround.+- If the Grok webhook is refused (an automation rate limit), `grok_wake` falls back+  to typing into the Grok Bot chat (`grok_chat_send`).++Other things to know on a Grok computer:++- **Use `auto` update mode.** Nobody clicks Install there.+- **One copy only.** The agent's shell may run the launcher from `~/.bashrc` at any+  time, including the moment a self-update restarts the app. Use the locked+  `run.sh` above, or two copies will fight.+- **The egress proxy is slow for large transfers** (about 2 MB/s measured).+  Relays 2.1.180+ keep a box connected while it is busy taking a file transfer.+- **Do not run `adom-bridge serve` on the box.** The app connects out to the user's+  relays and the mesh; a local relay is not needed.+- **KiCad** runs there as a Flatpak (`org.kicad.KiCad`) on the same X display. A+  KiCad bridge works only with a Linux build of that bridge.+- **Checking what the box shows:** `desktop_screenshot_screen` and+  `desktop_list_windows` work (2.1.181+).