chore: import upstream snapshot with attribution

docs/guides/TERMUX_GUIDE.md

@@ -0,0 +1,168 @@
+---
+title: "Termux Headless Setup"
+version: 3.8.40
+lastUpdated: 2026-06-28
+---
+
+# Termux Headless Setup
+
+OmniRoute can run as a headless server on Android through Termux. The Electron desktop app is not supported in Termux, but the web dashboard and OpenAI-compatible API work from the local browser or from other devices on the same network.
+
+## Prerequisites
+
+Install Termux from F-Droid or GitHub releases, then update packages and install the build tools required by native dependencies such as `better-sqlite3`.
+
+```bash
+pkg update
+pkg upgrade
+pkg install nodejs python build-essential git
+```
+
+> **Node.js version:** OmniRoute requires Node `>=22.22.2 <23 || >=24.0.0 <27` (matches `engines` in `package.json` / `SUPPORTED_NODE_RANGE`). Termux's `nodejs-lts` typically ships Node 20 LTS, which is **no longer supported** — install `pkg install nodejs` (current) instead and verify `node --version` reports a 22.x/24.x+ line.
+
+If native package compilation fails, rerun the `pkg install` command above and then retry the OmniRoute install.
+
+## Install
+
+Run the latest published package directly:
+
+```bash
+npx -y omniroute@latest
+```
+
+You can also install it globally:
+
+```bash
+npm install -g omniroute
+omniroute
+```
+
+## Run
+
+Start OmniRoute in headless server mode:
+
+```bash
+omniroute
+```
+
+or:
+
+```bash
+npx omniroute
+```
+
+The dashboard listens on:
+
+```text
+http://localhost:20128
+```
+
+Open that URL in the Android browser. If you run clients inside Termux, use the same host and port as the OpenAI-compatible base URL.
+
+## Background Execution
+
+For a simple background process:
+
+```bash
+nohup omniroute > omniroute.log 2>&1 &
+```
+
+To stop it:
+
+```bash
+pkill -f omniroute
+```
+
+For automatic startup after device boot, install the Termux:Boot add-on and create a boot script:
+
+```bash
+mkdir -p ~/.termux/boot
+cat > ~/.termux/boot/omniroute.sh <<'EOF'
+#!/data/data/com.termux/files/usr/bin/sh
+cd "$HOME"
+nohup omniroute > "$HOME/omniroute.log" 2>&1 &
+EOF
+chmod +x ~/.termux/boot/omniroute.sh
+```
+
+Android battery optimization can stop long-running background processes. Disable battery optimization for Termux if the server is expected to stay online.
+
+## Access From Other Devices
+
+Find the phone IP address on the WiFi network:
+
+```bash
+ip addr show wlan0
+```
+
+Then open the dashboard from another device:
+
+```text
+http://PHONE_IP:20128
+```
+
+For example:
+
+```text
+http://192.168.1.50:20128
+```
+
+Keep the phone and client on the same trusted network. If you expose OmniRoute outside the phone, enable API keys and dashboard authentication.
+
+## Data Directory
+
+By default OmniRoute stores data under the Termux home directory, following the same server-side data path behavior used on Linux. To place the database somewhere explicit:
+
+```bash
+export DATA_DIR="$HOME/.omniroute"
+omniroute
+```
+
+## Limitations
+
+- Electron does not run in Termux.
+- There is no system tray or desktop integration.
+- This setup is server-only: use the browser dashboard.
+- Native dependencies may need local compilation.
+- Low-memory Android devices may need fewer concurrent requests.
+- MITM/system certificate features may require Android-level trust-store work outside Termux.
+
+## Troubleshooting
+
+### better-sqlite3 Build Errors
+
+Install the Termux build toolchain:
+
+```bash
+pkg install nodejs python build-essential
+```
+
+Then rerun:
+
+```bash
+npx -y omniroute@latest
+```
+
+### Port Already In Use
+
+Check what is listening on the default port:
+
+```bash
+ss -ltnp | grep 20128
+```
+
+Stop the old process:
+
+```bash
+pkill -f omniroute
+```
+
+### Dashboard Not Reachable From Another Device
+
+Verify both devices are on the same WiFi network, then test from Termux:
+
+```bash
+curl http://localhost:20128
+```
+
+If local access works but LAN access does not, check Android hotspot/WiFi isolation and any firewall or VPN profile on the phone.