Termux Persistent Gateway

Keep an AI gateway running persistently on Android/Termux using tmux, wake-lock, auto-start on boot, and health monitoring without systemd.

--- 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 |