Termux Persistent Gateway

SKILL.md

--- name: termux-persistent-gateway description: "Keep an AI agent gateway running persistently on Android/Termux — tmux + wake-lock + auto-start on boot + health monitor. No systemd needed. Use when: (1) running a gateway on Termux/Android, (2) making gateway survive screen-off or reboots, (3) setting up auto-restart health monitoring on Termux." version: 1.1.0 author: kingofqin2026 license: MIT tags: [termux, android, gateway, persistent, tmux, wake-lock, auto-start] --- # Termux Persistent Gateway Keep your AI agent gateway alive on Android (no systemd), surviving screen-off, app-switching, and device reboots. ## Prerequisites ```bash pkg install tmux termux-api termux-boot ``` - **tmux** — terminal multiplexer, keeps the session alive when you close Termux - **termux-api** — provides `termux-wake-lock` / `termux-notification` - **termux-boot** — auto-start on device boot - **Android setting**: Settings > Apps > Termux > Battery > **Unrestricted** (critical — prevents Android from killing Termux) ## Configuration Before first use, edit the scripts to set: - **`GATEWAY_CMD`** — the command that starts your gateway (e.g. `openclaw gateway run`, `hermes gateway run`) - **`SESSION_NAME`** — the tmux session name (default: `agent-gw`) - **`LOG_DIR`** — where logs are stored (default: `~/.agent/logs`) All configurable values are at the top of each script — look for the `# === CONFIG ===` block. ## Quick Start ### Start the gateway ```bash bash <skill_dir>/scripts/run-gateway.sh ``` This script: 1. Acquires a wake lock (`termux-wake-lock`) so CPU stays alive 2. Kills any old gateway tmux session 3. Starts your gateway command inside a new tmux session 4. Logs output to the configured log directory ### Manage the session | Action | Command | |--------|---------| | Attach (see live output) | `tmux attach -t agent-gw` | | Detach | `Ctrl+B, D` | | Check if running | `tmux ls` | | View recent logs | `tail -f ~/.agent/logs/gateway-termux.log` | | Restart | kill session + run script again | ### Detach after attaching When you attach to tmux, press `Ctrl+B` then `D` (release both, press D) to detach without killing the session. The gateway keeps running. ## Auto-Start on Device Boot ### Step 1: Enable Termux:Boot ```bash pkg install termux-boot mkdir -p ~/.termux/boot/ ``` Open the **Termux:Boot** app from app drawer at least once to register it with Android. ### Step 2: Create boot script Copy the template and adjust paths: ```bash cp <skill_dir>/templates/termux-boot.sh ~/.termux/boot/agent-gateway chmod +x ~/.termux/boot/agent-gateway ``` Edit `~/.termux/boot/agent-gateway` to point `SCRIPT` at your `run-gateway.sh` path. The `sleep 15` gives Wi-Fi time to connect. Now the gateway auto-starts every time you reboot your phone. ## Health Monitoring (Cron) Optional: check on the gateway periodically and restart if it's down. ```bash bash <skill_dir>/scripts/healthcheck.sh ``` To schedule it, add to Termux cron: ```bash crontab -e # Add: */30 * * * * bash ~/.agent/scripts/healthcheck.sh ``` Or use your agent's cron system to run the healthcheck every 30 minutes. ## Verify It's Working ```bash # Check gateway is running tmux ls # Should show: agent-gw: 1 windows (created ...) # Check wake-lock is held termux-wake-lock 2>/dev/null || echo "wake-lock not acquired (probably already held)" ``` ## Troubleshooting | Problem | Fix | |---------|-----| | Gateway dies after screen off | Set Termux battery to **Unrestricted** | | Gateway dies after app close | Don't force-close Termux. Just swipe it away — tmux keeps running | | Boot auto-start doesn't work | Open **Termux:Boot** app once; check `~/.termux/boot/` script has execute permission | | "command not found" on boot | The boot script sources `.profile` to set PATH — ensure your gateway binary is in PATH | | tmux session shows "(dead)" | The gateway process crashed. Check logs, then re-run the startup script | | wake-lock fails | Make sure `termux-api` is installed and granted notification permission |