From e18217485a5a3a3319990a33b32274eb05391c8e Mon Sep 17 00:00:00 2001 From: mrbeandev Date: Mon, 16 Feb 2026 16:47:47 +0530 Subject: [PATCH] feat: add Android/Termux support with interactive manager and guide - Added assets/scripts/picoclaw-manager.sh: Interactive installer for Termux - Added docs/TERMUX_INSTALL.md: Comprehensive setup guide for Android users - Updated README.md: Added mobile support section Closes #286 --- README.md | 10 ++ assets/scripts/picoclaw-manager.sh | 180 +++++++++++++++++++++++++++++ docs/TERMUX_INSTALL.md | 99 ++++++++++++++++ 3 files changed, 289 insertions(+) create mode 100644 assets/scripts/picoclaw-manager.sh create mode 100644 docs/TERMUX_INSTALL.md diff --git a/README.md b/README.md index e80e2213c..f80c042f0 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,16 @@ docker compose logs -f picoclaw-gateway docker compose --profile gateway down ``` +## 📱 Mobile (Android / Termux) + +Run PicoClaw on your Android device with our interactive manager: + +```bash +pkg install -y curl && curl -sSL https://raw.githubusercontent.com/sipeed/picoclaw/main/assets/scripts/picoclaw-manager.sh -o picoclaw-manager.sh && chmod +x picoclaw-manager.sh && ./picoclaw-manager.sh +``` + +For detailed instructions, see the [Termux Installation Guide](docs/TERMUX_INSTALL.md). + ### Agent Mode (One-shot) ```bash diff --git a/assets/scripts/picoclaw-manager.sh b/assets/scripts/picoclaw-manager.sh new file mode 100644 index 000000000..9b80e3451 --- /dev/null +++ b/assets/scripts/picoclaw-manager.sh @@ -0,0 +1,180 @@ +#!/bin/bash + +# PicoClaw Manager for Termux +# A simple script to install, configure, and manage PicoClaw + +RED='\033[0;31m' +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +CONFIG_FILE="$HOME/.picoclaw/config.json" +REPO_DIR="$HOME/.picoclaw-repo" +BIN_PATH="$PREFIX/bin/picoclaw" + +show_header() { + clear + echo -e "${BLUE}" + cat << "EOF" +██████╗ ██╗ ██████╗ ██████╗ ██████╗██╗ █████╗ ██╗ ██╗ +██╔══██╗██║██╔════╝██╔═══██╗██╔════╝██║ ██╔══██╗██║ ██║ +██████╔╝██║██║ ██║ ██║██║ ██║ ███████║██║ █╗ ██║ +██╔═══╝ ██║██║ ██║ ██║██║ ██║ ██╔══██║██║███╗██║ +██║ ██║╚██████╗╚██████╔╝╚██████╗███████╗██║ ██║╚███╔███╔╝ +╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝╚══════╝╚═╝ ╚═╝ ╚══╝╚══╝ + +EOF + echo -e " 🦞 PicoClaw Termux Manager" + echo -e "==========================================${NC}" +} + +check_dependencies() { + echo -e "${YELLOW}[*] Checking dependencies...${NC}" + deps=("golang" "git" "make" "jq" "tmux") + to_install=() + for dep in "${deps[@]}"; do + if ! command -v "$dep" &> /dev/null; then + to_install+=("$dep") + fi + done + + if [ ${#to_install[@]} -ne 0 ]; then + echo -e "${YELLOW}[!] Installing missing packages: ${to_install[*]}${NC}" + pkg update && pkg install -y "${to_install[@]}" + else + echo -e "${GREEN}[✓] All dependencies found.${NC}" + fi +} + +install_picoclaw() { + check_dependencies + + echo -e "${YELLOW}[*] Cloning repository...${NC}" + if [ -d "$REPO_DIR" ]; then + cd "$REPO_DIR" && git pull + else + git clone https://github.com/sipeed/picoclaw.git "$REPO_DIR" + cd "$REPO_DIR" + fi + + echo -e "${YELLOW}[*] Building PicoClaw...${NC}" + # Adjust Go version + GO_VERSION=$(go version | awk '{print $3}' | sed 's/go//' | cut -d. -f1,2,3) + sed -i "s/go 1.25.7/go $GO_VERSION/" go.mod + + export CGO_ENABLED=0 + make deps + make build + + echo -e "${YELLOW}[*] Installing to bin...${NC}" + cp build/picoclaw-linux-arm64 "$BIN_PATH" + chmod +x "$BIN_PATH" + + if ! command -v picoclaw &> /dev/null; then + echo -e "${RED}[!] Installation failed. Bin not in PATH?${NC}" + else + echo -e "${GREEN}[✓] PicoClaw installed successfully!${NC}" + picoclaw onboard + fi + read -p "Press Enter to return to menu..." +} + +configure_picoclaw() { + if [ ! -f "$CONFIG_FILE" ]; then + echo -e "${RED}[!] Config file not found. Please install first.${NC}" + read -p "Press Enter to return to menu..." + return + fi + + echo -e "${BLUE}--- Configuration ---${NC}" + + # LLM Settings + read -p "Enter Gemini API Key (or press enter to skip): " gemini_key + if [ ! -z "$gemini_key" ]; then + jq ".providers.gemini.api_key = \"$gemini_key\" | .agents.defaults.provider = \"gemini\" | .agents.defaults.model = \"gemini-2.0-flash-lite\"" "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE" + echo -e "${GREEN}[✓] Gemini configured.${NC}" + fi + + # Telegram Settings + read -p "Enter Telegram Bot Token (or press enter to skip): " tg_token + if [ ! -z "$tg_token" ]; then + jq ".channels.telegram.enabled = true | .channels.telegram.token = \"$tg_token\" | .channels.telegram.allow_from = []" "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE" + echo -e "${GREEN}[✓] Telegram configured.${NC}" + fi + + echo -e "${GREEN}[✓] Configuration updated!${NC}" + read -p "Press Enter to return to menu..." +} + +manage_service() { + echo -e "${BLUE}--- Service Management ---${NC}" + echo "1) Start Gateway (in Tmux)" + echo "2) Stop Gateway" + echo "3) Restart Gateway" + echo "4) View Logs" + echo "5) Back" + read -p "Select option: " subopt + + case $subopt in + 1) + if tmux has-session -t picoclaw 2>/dev/null; then + echo -e "${YELLOW}[!] Session 'picoclaw' already exists.${NC}" + else + tmux new-session -d -s picoclaw "picoclaw gateway | tee $REPO_DIR/picoclaw.log" + echo -e "${GREEN}[✓] Gateway started in tmux session 'picoclaw'.${NC}" + fi + ;; + 2) + pkill -9 picoclaw + tmux kill-session -t picoclaw 2>/dev/null + echo -e "${YELLOW}[*] Gateway stopped.${NC}" + ;; + 3) + pkill -9 picoclaw + tmux kill-session -t picoclaw 2>/dev/null + sleep 1 + tmux new-session -d -s picoclaw "picoclaw gateway | tee $REPO_DIR/picoclaw.log" + echo -e "${GREEN}[✓] Gateway restarted.${NC}" + ;; + 4) + tail -f "$REPO_DIR/picoclaw.log" + ;; + *) return ;; + esac + read -p "Press Enter to return to menu..." +} + +uninstall_picoclaw() { + read -p "Are you sure you want to uninstall and delete all data? (y/N): " confirm + if [[ "$confirm" == "y" || "$confirm" == "Y" ]]; then + pkill -9 picoclaw + tmux kill-session -t picoclaw 2>/dev/null + rm "$BIN_PATH" + rm -rf "$REPO_DIR" + rm -rf "$HOME/.picoclaw" + echo -e "${GREEN}[✓] PicoClaw uninstalled.${NC}" + fi + read -p "Press Enter to return to menu..." +} + +while true; do + show_header + echo "1) Install / Update PicoClaw" + echo "2) Configure (API Keys / Telegram)" + echo "3) Start / Stop / Logs" + echo "4) Show Status" + echo "5) Uninstall" + echo "6) Exit" + read -p "Select option: " opt + + case $opt in + 1) install_picoclaw ;; + 2) configure_picoclaw ;; + 3) manage_service ;; + 4) picoclaw status; read -p "Press Enter to return to menu..." ;; + 5) uninstall_picoclaw ;; + 6) exit 0 ;; + *) echo -e "${RED}[!] Invalid option${NC}"; sleep 1 ;; + esac +done diff --git a/docs/TERMUX_INSTALL.md b/docs/TERMUX_INSTALL.md new file mode 100644 index 000000000..33cf5eb41 --- /dev/null +++ b/docs/TERMUX_INSTALL.md @@ -0,0 +1,99 @@ +# PicoClaw on Android (Termux) Installation Guide + +This guide provides two methods to install and run **PicoClaw** on your Android device. + +## 🚀 Recommended: Easy One-Line Manager +We have provided an interactive script to handle installation, configuration, and management automatically. + +Run this command in Termux: +```bash +pkg install -y curl && curl -sSL https://raw.githubusercontent.com/sipeed/picoclaw/main/assets/scripts/picoclaw-manager.sh -o picoclaw-manager.sh && chmod +x picoclaw-manager.sh && ./picoclaw-manager.sh +``` +*(Note: Replace with the actual URL once the script is added to the repo)* + +--- + +## 🛠️ Manual Method +If you prefer to set up everything manually, follow these steps: + +## Prerequisites +- Android device with **Termux** installed (Download from [F-Droid](https://f-droid.org/en/packages/com.termux/)). +- Working internet connection. + +## 1. Environment Setup +Open Termux and install the necessary packages: +```bash +pkg update && pkg upgrade +pkg install -y golang git make jq tmux +``` + +## 2. Clone and Prepare PicoClaw +```bash +git clone https://github.com/sipeed/picoclaw.git ~/.picoclaw-repo +cd ~/.picoclaw-repo +``` + +### Fix Go Version Requirement +Termux might have a slightly older version of Go than required by `go.mod`. Use this command to automatically adjust the requirement to match your installed Go version: +```bash +sed -i "s/go 1.25.7/go $(go version | awk '{print $3}' | sed 's/go//' | cut -d. -f1,2,3)/" go.mod +``` + +### Build and Install PicoClaw +Build the project with CGO disabled for maximum compatibility across different Android architectures, then move it to your system PATH: +```bash +export CGO_ENABLED=0 +make deps +make build + +# Install to Termux bin directory +cp build/picoclaw-linux-arm64 $PREFIX/bin/picoclaw +chmod +x $PREFIX/bin/picoclaw +``` + +Now you can run `picoclaw` from anywhere! + +## 3. Initial Configuration +Initialise the workspace and generate a default configuration: +```bash +picoclaw onboard +``` + +This creates the configuration file at `~/.picoclaw/config.json`. + +## 4. Connect to LLM and Telegram +Edit your configuration to add your Gemini (or other) API key and Telegram bot token: + +### Add API Key (Gemini Example) +```bash +# Replace YOUR_GEMINI_KEY with your actual key +GEMINI_KEY="YOUR_GEMINI_KEY" +jq ".providers.gemini.api_key = \"$GEMINI_KEY\" | .agents.defaults.provider = \"gemini\" | .agents.defaults.model = \"gemini-2.0-flash-lite\"" ~/.picoclaw/config.json > ~/.picoclaw/config.json.tmp && mv ~/.picoclaw/config.json.tmp ~/.picoclaw/config.json +``` + +### Enable Telegram Bot +```bash +# Replace YOUR_BOT_TOKEN with your Telegram token +TELEGRAM_TOKEN="YOUR_BOT_TOKEN" +jq ".channels.telegram.enabled = true | .channels.telegram.token = \"$TELEGRAM_TOKEN\" | .channels.telegram.allow_from = []" ~/.picoclaw/config.json > ~/.picoclaw/config.json.tmp && mv ~/.picoclaw/config.json.tmp ~/.picoclaw/config.json +``` + +## 5. Running PicoClaw +It's recommended to run PicoClaw inside a `tmux` session so it keeps running in the background: + +```bash +# Start a new tmux session named 'picoclaw' +tmux new -s picoclaw + +# Inside tmux, start the gateway +picoclaw gateway +``` + +To detach from tmux, press `Ctrl+B` then `D`. +To re-attach later: `tmux attach -t picoclaw`. + +## 6. Success! +Once the gateway is running, you should see: +`[INFO] telegram: Telegram bot connected {username=...}` + +You can now chat with your PicoClaw assistant directly on Telegram!