#!/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

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"

---
name: adom-bridge-linux
description: >-
  For Adom Bridge running on a Linux machine (the AppImage), not the adom-bridge CLI in a
  container: install one copy, self-update, what is still Windows-only, Grok Bot computers
  (wake with grok_wake). Use when installing, updating or debugging ab on Linux, or a Linux
  mesh peer is 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.

Bridges on Linux (2.1.184+): `bridge_install` keeps the zip's file modes, so a
native `spawn.entrypoints.linux` binary is executable (ab also sets the bit before
spawning). Reinstalling a running bridge stops the old process first and says so
(`stoppedPids`, `restarted`); the next verb starts the new build. `bridge_list`
shows live pids.

## 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+).