's'

README.md

@@ -18,6 +18,7 @@ It keeps only the parts that were actually used:
 - `bootstrap_redroid.py`
 - `verify_offline_bundle.py`
 - `tools/compat.py` (host / GPU / runtime checks)
+- `tools/ssh_remote.py` (Paramiko SSH: remote `docker` / `adb` diagnostics)
 - `offline/README.md`
 - `offline/manifest.json`
 - `stuff/mindthegapps.py`
@@ -75,15 +76,15 @@ The project probes the **host** before critical steps (no separate manual checkl
 
 **GPU mode (`run_redroid.py`):**
 
-- **`--gpu-mode auto` (default):** uses **`host`** when DRI devices exist and automatically adds `docker run --device …` for each `/dev/dri/card*` / `renderD*` node; otherwise **`guest`** (software GLES).
+- **`--gpu-mode guest` (default):** software GLES — most stable on headless / server GPUs where host EGL inside the guest often breaks boot or **adbd**.
+- **`--gpu-mode auto`:** stays **`guest`** unless **`REDROID_USE_HOST_GPU=1`** (or `true`/`yes`/`on`) **and** `/dev/dri` nodes exist; then **`host`** and `docker run --device …` per DRI node.
 - **`--gpu-mode host`:** pass-through when DRI exists; otherwise **falls back to `guest`** with a warning.
-- **`--gpu-mode guest`:** force software rendering (common black-screen case on headless servers).
 
 Quick probe only:
 
 ```bash
 python tools/compat.py
-python tools/compat.py -c podman --gpu-mode auto
+python tools/compat.py -c podman --gpu-mode guest
 ```
 
 ## Build the 5570 image
@@ -131,6 +132,12 @@ python run_redroid.py \
   --adb-insecure
 ```
 
+On the **same machine as Docker**, one-shot status + logs + `logcat` after start:
+
+```bash
+python run_redroid.py ... --adb-insecure --diagnose --diagnose-settle 20
+```
+
 Then:
 
 ```bash
@@ -145,6 +152,36 @@ If you still see `unauthorized` after an upgrade, stop the container, remove per
 rm -rf ~/data-redroid13/misc/adb
 ```
 
+## Remote diagnostics over SSH (Paramiko)
+
+When redroid runs on **another Linux machine**, you can drive checks from your PC with **`tools/ssh_remote.py`** (uses [Paramiko](https://www.paramiko.org/), declared in `requirements.txt`).
+
+**Do not put passwords in Git.** Use a key file or a one-time prompt:
+
+```bash
+pip install -r requirements.txt
+export REDROID_SSH_HOST=192.168.2.179
+export REDROID_SSH_USER=eric
+python tools/ssh_remote.py --password-prompt diagnose
+```
+
+Key-based:
+
+```bash
+export REDROID_SSH_HOST=... REDROID_SSH_USER=eric REDROID_SSH_KEY=$HOME/.ssh/id_ed25519
+python tools/ssh_remote.py diagnose
+```
+
+Optional env: **`REDROID_CONTAINER`** (default `redroid_13.0.0_mindthegapps_houdini_magisk`), **`REDROID_ADB_PORT`** (default `5570`). You can also pass **`--container-name`** / **`--adb-port`**.
+
+Arbitrary remote command (note the **`--`** before the shell snippet):
+
+```bash
+python tools/ssh_remote.py -H 192.168.2.179 -U eric --password-prompt exec -- bash -lc 'docker ps -a | head -20'
+```
+
+The `shell` subcommand is a minimal pseudo-shell only; for a full TTY, use normal OpenSSH **`ssh`**.
+
 ## ADB `failed to connect` / connection refused
 
 This means **nothing is listening on the host port** (not the same as `unauthorized`). Typical causes:
@@ -158,11 +195,11 @@ This means **nothing is listening on the host port** (not the same as `unauthori
 
 ## Black screen or flickering
 
-With **`--gpu-mode guest`** (or **`auto`** when no `/dev/dri` exists), the display uses **software GLES** (SwiftShader). On many **headless servers**, SurfaceFlinger may show a **black screen**, **flicker**, or very low FPS. That is a **display stack** issue, not ADB. The default **`auto`** mode uses **host** GPU when DRI nodes are visible and injects **`--device`** flags automatically.
+With **`--gpu-mode guest`** (the default), the display uses **software GLES** (SwiftShader). On many **headless servers**, SurfaceFlinger may still show **black screen** or **flicker** — try **`--soft-display`** and more RAM. Host GPU needs **`REDROID_USE_HOST_GPU=1`** with **`--gpu-mode auto`** or **`--gpu-mode host`** when DRI works inside the guest.
 
 **What to try**
 
-1. **GPU on the host:** **`--gpu-mode auto`** (default) enables **host** when `/dev/dri` exists. If the instance **crashes** or **ADB never connects**, host EGL may be incompatible — fall back to **`--gpu-mode guest`**. If you must pass devices manually, for example:
+1. **GPU on the host:** set **`REDROID_USE_HOST_GPU=1`** and **`--gpu-mode auto`**, or **`--gpu-mode host`**. If **ADB never connects**, host EGL is likely broken — use default **`--gpu-mode guest`**. Manual devices example:
    ```bash
    docker run ... --device /dev/dri ...
    ```