{"id":51182908,"url":"https://github.com/carrilloapps/picoclaw-dotfiles","last_synced_at":"2026-06-27T08:02:07.432Z","repository":{"id":347884804,"uuid":"1195561211","full_name":"carrilloapps/picoclaw-dotfiles","owner":"carrilloapps","description":"🦞 PicoClaw Dotfiles — Deploy a 24/7 AI assistant on an old Android phone One-click installer.","archived":false,"fork":false,"pushed_at":"2026-03-29T21:52:29.000Z","size":949,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T00:43:59.561Z","etag":null,"topics":["adb-automation","ai-assistant","android","picoclaw","telegram-bot-ai-assistant","termux"],"latest_commit_sha":null,"homepage":"https://carrillo.app","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carrilloapps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"carrilloapps","custom":["https://carrillo.app/donate"]}},"created_at":"2026-03-29T20:04:43.000Z","updated_at":"2026-03-29T21:52:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/carrilloapps/picoclaw-dotfiles","commit_stats":null,"previous_names":["carrilloapps/picoclaw-dotfiles"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/carrilloapps/picoclaw-dotfiles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fpicoclaw-dotfiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fpicoclaw-dotfiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fpicoclaw-dotfiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fpicoclaw-dotfiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carrilloapps","download_url":"https://codeload.github.com/carrilloapps/picoclaw-dotfiles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carrilloapps%2Fpicoclaw-dotfiles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34845749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adb-automation","ai-assistant","android","picoclaw","telegram-bot-ai-assistant","termux"],"created_at":"2026-06-27T08:02:03.181Z","updated_at":"2026-06-27T08:02:07.425Z","avatar_url":"https://github.com/carrilloapps.png","language":"Shell","funding_links":["https://github.com/sponsors/carrilloapps","https://carrillo.app/donate"],"categories":[],"sub_categories":[],"readme":"\u003c!-- SEO: PicoClaw Dotfiles for Android - Deploy AI assistant on Android phone via Termux --\u003e\n\u003c!-- Keywords: picoclaw, picoclaw dotfiles, android ai assistant, termux ai, telegram bot android, self-hosted ai, llm on phone, gemini android, gpt android termux --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/carrilloapps/picoclaw-dotfiles\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.svg\"\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo.svg\"\u003e\n      \u003cimg src=\"assets/logo.svg\" alt=\"PicoClaw Dotfiles for Android - Deploy an AI assistant on any Android phone via Termux\" width=\"480\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/carrilloapps/picoclaw-dotfiles?style=flat\u0026color=22c55e\" alt=\"MIT License\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://github.com/sipeed/picoclaw/releases\"\u003e\u003cimg src=\"https://img.shields.io/badge/picoclaw-v0.2.6-3E5CB8?style=flat\" alt=\"PicoClaw v0.2.6\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://termux.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-Android_11+-3DDC84?style=flat\u0026logo=android\u0026logoColor=white\" alt=\"Android 11+\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://github.com/carrilloapps/picoclaw-dotfiles/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/carrilloapps/picoclaw-dotfiles/ci.yml?style=flat\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Deploy a self-healing AI assistant on any old Android phone.\u003cbr\u003e\n  \u003csub\u003e25+ LLM models \u0026bull; Telegram bot with voice \u0026bull; full device control \u0026bull; zero maintenance\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\n    \u003ca href=\"https://carrillo.app\"\u003e\u003cstrong\u003ecarrillo.app\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;\u0026middot;\u0026nbsp;\n    \u003ca href=\"https://linkedin.com/in/carrilloapps\"\u003eLinkedIn\u003c/a\u003e \u0026nbsp;\u0026middot;\u0026nbsp;\n    \u003ca href=\"https://t.me/carrilloapps\"\u003eTelegram\u003c/a\u003e \u0026nbsp;\u0026middot;\u0026nbsp;\n    \u003ca href=\"mailto:m@carrillo.app\"\u003em@carrillo.app\u003c/a\u003e\n  \u003c/sub\u003e\n  \u003cbr\u003e\n  \u003csub\u003eBy \u003ca href=\"https://github.com/carrilloapps\"\u003e\u003cstrong\u003eJosé Carrillo\u003c/strong\u003e\u003c/a\u003e \u0026mdash; Senior Fullstack Developer \u0026 Tech Lead\u003c/sub\u003e\n\u003c/p\u003e\n\n---\n\n**PicoClaw Dotfiles for Android** is a complete deployment toolkit for [PicoClaw](https://github.com/sipeed/picoclaw) -- an ultra-lightweight AI assistant (single Go binary, ~28 MB) that runs on any Android phone via [Termux](https://termux.dev). Cloud providers (Azure OpenAI, Google Gemini, Ollama, Groq) handle LLM inference, so even a 5-year-old phone becomes a 24/7 self-healing AI assistant with Telegram integration, voice support, device control, and 146 MCP tools. No root required.\n\n\u003e [!WARNING]\n\u003e **Disclaimer**: This project is provided as-is under the [MIT License](LICENSE). Use at your own risk. The author is not responsible for damage to devices, data loss, or API charges. API keys and cloud services may incur costs from their respective providers. Always review scripts before running them. PicoClaw is developed by [Sipeed](https://github.com/sipeed/picoclaw) -- this repo only provides deployment configuration and dotfiles.\n\n---\n\n## The Device\n\nThis implementation runs on a **Xiaomi Redmi Note 10 Pro** -- an old phone repurposed as a dedicated AI server.\n\n| | |\n| --- | --- |\n| **Model** | Xiaomi Redmi Note 10 Pro (M2101K6R, codename `sweet`) |\n| **SoC** | Qualcomm Snapdragon 732G (SM7150) |\n| **CPU** | Qualcomm Kryo 470 -- 8 cores, big.LITTLE @ 1.80 GHz |\n| **RAM** | 6 GB LPDDR4X + 2 GB swap |\n| **Storage** | 128 GB UFS 2.2 |\n| **Display** | 6.67\" AMOLED, 1080x2400 |\n| **Camera** | 108 MP (back), 16 MP (front) |\n| **OS** | Android 16 (API 36) via PixelOS custom ROM |\n| **Kernel** | 4.14.x (SMP PREEMPT) |\n\n\u003e Any Android 11+ phone with `aarch64` (ARM64) works. The whole point is to give old hardware a second life.\n\n---\n\n## Gallery\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"assets/photo-front.jpg\" alt=\"Xiaomi Redmi Note 10 Pro running PicoClaw in Termux\" width=\"360\"\u003e\u003cbr\u003e\n      \u003cem\u003eFront -- PicoClaw running in Termux\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cimg src=\"assets/photo-back.jpg\" alt=\"Xiaomi Redmi Note 10 Pro back with 108MP camera\" width=\"360\"\u003e\u003cbr\u003e\n      \u003cem\u003eBack -- 108 MP quad camera, Snapdragon 732G\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTermux screenshot (PicoClaw status)\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\u003cimg src=\"assets/screenshot-termux.png\" alt=\"Termux running PicoClaw on the Xiaomi Redmi Note 10 Pro\" width=\"360\"\u003e\n\u003cbr\u003e\u003cbr\u003e\nPicoClaw v0.2.6 running inside Termux on Android 16. Shows the status output with model, config path, workspace, and auth state.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eNeofetch (device specs)\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\u003cimg src=\"assets/neofetch.jpg\" alt=\"Neofetch output showing Android 16, Snapdragon 732G, 6 GB RAM\" width=\"720\"\u003e\n\u003cbr\u003e\u003cbr\u003e\nAndroid 16 (aarch64), Kernel 4.14, Qualcomm Snapdragon 732G, 6 GB RAM, 275 packages. The bottom section shows detailed hardware info from getprop (Xiaomi, sweet, M2101K6R).\n\u003c/details\u003e\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Android Device -- Termux\"\n        GW[\"PicoClaw Gateway\u003cbr/\u003etmux session\"]\n        ADB[\"ADB Self-Bridge\u003cbr/\u003eauto-detect port\"]\n        WD[\"Watchdog\u003cbr/\u003eevery 60s\"]\n        UI[\"UI Automation\u003cbr/\u003e40+ commands\"]\n        CAM[\"Camera / Mic\u003cbr/\u003eScreenshot / Sensors\"]\n        MCP[\"MCP Servers\u003cbr/\u003e146 tools\"]\n    end\n\n    subgraph \"Cloud Providers\"\n        GG[\"Google AI Studio\u003cbr/\u003eGemini 2.5\"]\n        AZ[\"Azure OpenAI\u003cbr/\u003eGPT-4o\"]\n        OL[\"Ollama Cloud\u003cbr/\u003eDeepSeek, Qwen\"]\n        GQ[\"Groq\u003cbr/\u003efast + STT\"]\n        TTS[\"Edge TTS\u003cbr/\u003e6 voices\"]\n    end\n\n    subgraph \"Messaging\"\n        TG[\"Telegram Bot\"]\n    end\n\n    subgraph \"Workstation (optional)\"\n        WS[\"SSH + Makefile\u003cbr/\u003eremote management\"]\n    end\n\n    WS --\u003e|\"paramiko\"| GW\n    GW --\u003e|\"long poll\"| TG\n    GW --\u003e GG\n    GW --\u003e AZ\n    GW --\u003e OL\n    GW --\u003e GQ\n    GW --\u003e TTS\n    GW --\u003e ADB\n    GW --\u003e MCP\n    ADB --\u003e UI\n    ADB --\u003e CAM\n    WD --\u003e|\"auto-restart\"| GW\n\n    style GG fill:#4285F4,color:#fff\n    style AZ fill:#0078d4,color:#fff\n    style GQ fill:#f55036,color:#fff\n    style TG fill:#0088cc,color:#fff\n```\n\n---\n\n## Highlights\n\n- **25+ LLM models** across 5 providers with **automatic failover** (Azure → Ollama → Antigravity → Google) and hot-swap from chat\n- **Telegram bot** with voice messages (STT + TTS), typing indicators, and streaming\n- **Full device control** -- 44 permissions + 40 appops, ADB self-bridge, UI automation, camera, mic, sensors\n- **5-layer resilience** -- Termux:Boot + watchdog (60s) + job-scheduler (5min) + .bashrc guards + wake lock\n- **Auto-detection** -- dynamic IP discovery, ADB port scanning, workstation device finder\n- **Auto-failover** -- LLM provider health checks on boot and on 429/500/503 errors (5min cooldown)\n- **Power tools** -- PDF/image OCR, video download, RAG (SQLite FTS5), code interpreter, workflows, webhooks, scheduling\n- **Headless browser** -- Chromium CDP for DOM extraction, screenshots, PDF rendering, CSS scraping\n- **Polyglot code runner** -- Go, Rust, PHP, Ruby, Perl, Lua, Deno, Java, Kotlin, Swift, Elixir, Zig (16+ languages)\n- **Central memory** -- every conversation flows through RAG, context shared across all LLM switches\n- **Hybrid RAG** -- BM25 + Gemini embeddings with Reciprocal Rank Fusion (semantic + keyword)\n- **Auto-ingestion** -- gateway log auto-indexed every 2 min into RAG with embeddings\n- **Cloudflare Tunnel** -- token-based or quick mode (works on Termux via proot), HMAC + CF Access JWT\n- **Self-modifying** -- agent can change personality, install capabilities, upgrade itself, manage packages, backup/restore — all from chat\n- **Live channel config** -- add/remove Telegram users, configure WhatsApp/Discord/etc. without restarting\n- **146 MCP tools** via 4 servers (filesystem, memory, sequential-thinking, github)\n- **Voice pipeline** -- 6 TTS voices (Spanish + English), Whisper STT with provider cascade\n- **Notification reading** -- via ADB shell (no Android listener permission required)\n- **Web scraping** -- curl+BS4, Node/cheerio, screenshot fallback\n- **One-click installer** -- single `install.sh` sets up everything: binary, config, scripts, cron, security\n- **Remote device control** -- manage other phones via USB OTG from Telegram\n- **Remote management** -- 30+ Makefile targets, 13 Python scripts, all via SSH\n- **Security hardened** -- `chmod 600` secrets, `chmod 700` scripts, gateway on localhost only, SSH hardened\n\n---\n\n## What You Need\n\n| | Required | Details |\n|-|----------|---------|\n| 1 | **Android phone** | Android 11+ with ARM64 (`aarch64`). Any phone from 2018 onwards. |\n| 2 | **WiFi** | For cloud LLM inference. The phone must stay connected. |\n| 3 | **At least one API key** | [Ollama Cloud](https://ollama.com) (free) is the easiest option. |\n\n\u003e **No computer required.** Everything can be done from the phone itself. A computer is optional and only adds remote management via SSH.\n\n### Optional\n\n| Item | What it adds |\n|------|-------------|\n| **Computer** (Windows/macOS/Linux) | Remote management via SSH, Makefile, automated deploy |\n| **Telegram account** | Control PicoClaw via Telegram (text + voice messages) |\n| **Google AI Studio key** ([free](https://aistudio.google.com/apikey)) | Gemini 2.5 Flash/Pro models |\n| **Groq API key** ([free](https://console.groq.com)) | Voice message transcription (Whisper STT) |\n| **Azure OpenAI key** | GPT-4o as primary model (enterprise quality, paid) |\n\n---\n\n## Installation\n\nChoose your path. Both produce the exact same result: a fully operational, self-healing PicoClaw instance.\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003ch3\u003ePath A: Phone only (no computer)\u003c/h3\u003e\u003c/summary\u003e\n\nEverything is done from the phone screen. No computer, no USB cable, no SSH.\n\n\u003e **Time**: ~20 minutes. **Difficulty**: Beginner-friendly.\n\n#### A1. Initial phone setup\n\nIf the phone is factory-fresh:\n\n1. **Power on** and complete the Android setup wizard (language, WiFi, skip Google account or sign in)\n2. **Connect to WiFi** -- this is required for everything that follows\n3. **Disable battery optimization for Termux later** (explained in step A5)\n\n#### A2. Install Termux from F-Droid\n\n\u003e **Warning**: Do NOT install Termux from Google Play. That version is abandoned (v0.101) and will not work.\n\n1. Open the **browser** on the phone and go to **https://f-droid.org**\n2. Tap **\"Download F-Droid\"** and install the APK\n   - If Android blocks the install: **Settings \u003e Apps \u003e [your browser] \u003e Install unknown apps \u003e Allow**\n3. Open **F-Droid**, wait for it to update its repository, then search and install:\n   - **Termux** (by Fredrik Fornwall) -- the terminal app\n   - **Termux:Boot** -- runs scripts on device boot\n   - **Termux:API** -- access to camera, mic, GPS, SMS, sensors\n4. **Open Termux:Boot once** after installing (just open it and close it -- Android needs to register it)\n\n#### A3. Get your API keys\n\nYou need at least one LLM provider. Open the browser on the phone and sign up:\n\n| Provider | URL | Cost | What you get |\n|----------|-----|------|-------------|\n| **Ollama Cloud** | [ollama.com](https://ollama.com) | Free | 8 models (DeepSeek, Qwen, GPT-OSS) |\n| **Google AI Studio** | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | Free | Gemini 2.5 Flash / Pro |\n| Groq | [console.groq.com](https://console.groq.com) | Free | Fast inference + Whisper STT for voice |\n| Azure OpenAI | [portal.azure.com](https://portal.azure.com) | Paid | GPT-4o (best quality) |\n\nCopy your API key(s) to a notes app so you can paste them during installation.\n\n#### A4. (Optional) Create a Telegram bot\n\nTo control PicoClaw from Telegram with text and voice messages:\n\n1. Open **Telegram** \u003e search **@BotFather** \u003e send `/newbot`\n2. Follow the prompts to name your bot. Copy the **bot token** (format: `123456789:ABCdef...xyz`)\n3. Search **@userinfobot** \u003e send any message. Copy your **numeric user ID**\n\n#### A5. Run the installer\n\nOpen the **Termux** app and run:\n\n```bash\npkg update \u0026\u0026 pkg upgrade -y\npkg install -y curl\ncurl -sL https://raw.githubusercontent.com/carrilloapps/picoclaw-dotfiles/main/utils/install.sh | bash\n```\n\nThe installer will prompt you for:\n- **Packages** -- type `Y` to install (~225 packages, takes a few minutes)\n- **Ollama API key** -- paste it (or press Enter to skip)\n- **Google AI Studio / Azure / Groq keys** -- paste or Enter to skip\n- **Telegram bot token + user ID** -- paste or Enter to skip\n- **Device screen unlock PIN** -- for auto-unlock features (or Enter to skip)\n\nWhen it says `Installation complete!`, PicoClaw is running.\n\n#### A6. Verify\n\n```bash\n./picoclaw status\n```\n\nYou should see `Config: ... ✓` and your model name. If you set up Telegram, send a message to your bot -- it should reply.\n\n#### A7. (Optional) Grant full Android permissions\n\n\u003e **Without this step**, PicoClaw works but can't use the camera, microphone, UI automation, SMS reading, or notifications. If you only need text chat via Telegram, you can skip this.\n\nThis uses Android's Wireless Debugging feature to grant permissions from the phone itself:\n\n**Enable Developer Options:**\n\n1. **Settings \u003e About Phone** \u003e tap **\"Build number\"** 7 times\n2. **Settings \u003e System \u003e Developer Options** \u003e enable **USB Debugging**\n3. In the same screen, enable **Wireless Debugging** \u003e tap it to open its settings\n\n**Pair Termux with ADB:**\n\n1. Tap **\"Pair device with pairing code\"** -- a dialog shows a **6-digit code** and an **IP:Port**\n2. **Don't close this dialog.** Switch to Termux (app switcher or swipe) and type:\n\n```bash\nadb pair \u003cIP:PORT_FROM_DIALOG\u003e\n# Example: adb pair 192.168.1.101:42383\n# Then type the 6-digit code when prompted\n```\n\n3. You should see `Successfully paired`\n\n**Connect and grant:**\n\n1. Go back to the **Wireless Debugging** main screen (not the pair dialog)\n2. Note the **IP:Port** shown at the top (different from the pair port)\n3. In Termux:\n\n```bash\nadb connect \u003cIP:PORT_FROM_SCREEN\u003e\n# Example: adb connect 192.168.1.101:41777\n```\n\n4. A dialog pops up: **\"Allow USB debugging?\"** -- tap **Allow** (check \"Always allow\")\n5. Grant all permissions:\n\n```bash\nbash ~/picoclaw-dotfiles/utils/grant-permissions.sh\n```\n\n6. Set up the permanent self-bridge:\n\n```bash\nadb connect localhost:5555\n# Accept the \"Allow?\" dialog again\n```\n\nDone. Permissions are granted permanently. The self-bridge auto-reconnects on reboot.\n\n#### A8. All done\n\n```bash\n./picoclaw status                    # Check status\n./picoclaw agent -m \"Hello!\"         # Chat with the AI\ntmux attach -t picoclaw              # View gateway logs (Ctrl+B, D to detach)\n~/bin/notifications.sh --summary     # Read phone notifications\n~/bin/ui-control.sh status           # Screen, battery, current app\n```\n\n\u003e **On reboot**: Everything starts automatically via Termux:Boot. The watchdog checks every 60 seconds. You never need to open Termux manually.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003ePath B: With a computer (remote deploy)\u003c/h3\u003e\u003c/summary\u003e\n\nThe computer manages the phone over WiFi via SSH. Faster for experienced users and required for ongoing remote management.\n\n\u003e **Time**: ~15 minutes. **Difficulty**: Intermediate (SSH, command line).\n\n#### B1. Prepare the phone\n\nOn the phone itself (only needed once):\n\n1. Complete Android setup if factory-fresh (WiFi, language)\n2. Install **Termux** from [F-Droid](https://f-droid.org/en/packages/com.termux/) (**not** Google Play)\n3. Also install **Termux:Boot** and **Termux:API** from F-Droid\n4. Open **Termux:Boot** once (just open and close)\n5. Open **Termux** and run:\n\n```bash\npkg update \u0026\u0026 pkg upgrade -y\npkg install -y openssh\npasswd    # Set a password -- you'll need it for SSH\nsshd      # Start the SSH server\n```\n\n6. Find the IP and username:\n\n```bash\nifconfig wlan0 | grep 'inet '   # Note the IP (e.g., 192.168.1.101)\nwhoami                            # Note the username (e.g., u0_a39)\n```\n\n\u003e **Tip**: You can put the phone down now. Everything else is done from the computer.\n\n#### B2. Set up the computer\n\n```bash\ngit clone https://github.com/carrilloapps/picoclaw-dotfiles.git\ncd picoclaw-dotfiles\npip install paramiko python-dotenv\ncp .env.example .env\n```\n\nEdit `.env` with the values from step B1 and your API keys:\n\n```bash\nDEVICE_SSH_HOST=192.168.1.101       # From ifconfig\nDEVICE_SSH_PORT=8022\nDEVICE_SSH_USER=u0_a39              # From whoami\nDEVICE_SSH_PASSWORD=YourPassword    # From passwd\n\nOLLAMA_API_KEY=your_key_here        # From ollama.com\nOLLAMA_MODEL=gpt-oss:120b\n\n# Optional: add Azure, Groq, Telegram keys (see .env.example)\n```\n\nTest the connection:\n\n```bash\npython scripts/connect.py \"echo OK\"\n```\n\n#### B3. Deploy\n\n```bash\npython scripts/full_deploy.py\n```\n\nThis runs 12 automated steps: installs packages, deploys scripts, generates config, starts the gateway, and verifies everything. Takes ~5 minutes.\n\n#### B4. Grant Android permissions\n\nChoose one method:\n\n**Wireless (no USB cable):**\n\n1. On the phone: **Settings \u003e Developer Options \u003e Wireless Debugging \u003e Pair device with pairing code**\n2. On the computer:\n\n```bash\nadb pair \u003cIP\u003e:\u003cPAIR_PORT\u003e \u003cCODE\u003e          # From the pairing dialog\nadb connect \u003cIP\u003e:\u003cDEBUG_PORT\u003e             # From the Wireless Debugging main screen\nbash utils/grant-permissions.sh           # Grant everything\npython scripts/connect.py \"adb connect localhost:5555\"  # Self-bridge\n```\n\n3. Accept the \"Allow USB debugging?\" dialogs on the phone (2 times)\n\n**USB cable:**\n\n```bash\n# Connect phone via USB\nadb devices                               # Accept prompt on phone\nbash utils/grant-permissions.sh           # Grant everything\n# Unplug the cable -- ADB TCP is now enabled\n```\n\n#### B5. Verify\n\n```bash\nmake status                  # PicoClaw status\nmake health                  # Gateway health check\nmake agent MSG=\"Hello\"       # Chat with the AI\nmake info                    # Full device diagnostic\nmake verify                  # 8-phase resilience test\n```\n\n#### B6. Ongoing management\n\nAll commands run over SSH from the computer. No need to touch the phone:\n\n```bash\nmake gateway-restart         # Restart gateway\nmake gateway-logs            # View gateway logs\nmake model M=deepseek-v3.2  # Switch LLM model\nmake config                  # View config (secrets masked)\nmake models                  # List all 25 available models\n```\n\nIf the phone's IP changes:\n\n```bash\npython scripts/find_device.py --update   # Auto-discover and update .env\n```\n\n\u003c/details\u003e\n\n### What the installer sets up\n\nRegardless of which path you choose, the result is identical:\n\n| Component | Details |\n|-----------|---------|\n| **PicoClaw v0.2.6** | Go binary (28 MB, aarch64) with TLS wrapper |\n| **47 device scripts** | UI automation, voice, notifications, media, ADB, watchdog, webhook CRUD, log rotation |\n| **4 MCP servers** | filesystem, memory, sequential-thinking, github (146 tools) |\n| **5-layer resilience** | Termux:Boot + watchdog (60s) + job-scheduler (5min) + .bashrc guards + wake lock |\n| **5 cron jobs** | Watchdog, media cleanup, disk monitor, session cleanup, hourly log rotation |\n| **Security** | `chmod 600` secrets, `chmod 700` scripts, gateway on `127.0.0.1` only |\n| **Telegram bot** | Long-polling gateway with voice (STT+TTS), if configured |\n\n---\n\n## Documentation\n\nDetailed step-by-step guides are in the [`docs/`](docs/) directory:\n\n| Guide | Topics |\n| ----- | ------ |\n| [00 - Termux \u0026 SSH Setup](docs/00-termux-ssh-setup.md) | Termux install, SSH server, find user/IP, connect from workstation |\n| [01 - Hardware Setup](docs/01-hardware-setup.md) | Device requirements, Termux apps, ADB setup (USB + wireless) |\n| [02 - PicoClaw Installation](docs/02-picoclaw-installation.md) | Binary download, TLS fix, config, security.yml (v0.2.6) |\n| [03 - Providers Setup](docs/03-providers-setup.md) | Azure, Ollama, Groq, Antigravity, model switching |\n| [04 - Telegram Integration](docs/04-telegram-integration.md) | Bot setup, voice pipeline (STT + TTS), 6 voices |\n| [05 - Device Control](docs/05-device-control.md) | ADB self-bridge, 44 permissions, UI automation, notifications |\n| [06 - Resilience](docs/06-resilience.md) | 5-layer resilience, boot script, watchdog, 8-phase verification |\n| [07 - Skills and MCP](docs/07-skills-and-mcp.md) | Skills, 4 MCP servers, 146 tools |\n| [08 - Advanced Features](docs/08-advanced-features.md) | Web scraping, knowledge base, cron jobs |\n| [09 - Remote Devices](docs/09-remote-devices.md) | Control other phones via USB OTG |\n| [10 - Complete Setup Guide](docs/10-complete-setup-guide.md) | End-to-end from zero to running (all phases, troubleshooting) |\n| [11 - Power Tools](docs/11-power-tools.md) | PDF, image, RAG, code-run, media, workflows, webhooks, browser, Cloudflare |\n| [12 - vs OpenClaw](docs/12-vs-openclaw.md) | Capability comparison table — where PicoClaw wins |\n| [13 - Central Memory](docs/13-central-memory.md) | RAG-as-memory: shared context across LLM switches |\n| [14 - Self-Administration](docs/14-self-administration.md) | Live channels, backup/restore/upgrade, pkg mgmt — all from chat |\n| [15 - Webhook Security](docs/15-webhook-security.md) | Honeypot, tiered rate limits, auto-ban, HMAC, CF Access, hardening headers |\n| [16 - Resilience \u0026 Dynamic Webhooks](docs/16-resilience-and-dynamic-webhooks.md) | Reboot recovery, network fallback, chat-created forms/endpoints |\n\n---\n\n## Repository Structure\n\n```\npicoclaw-dotfiles/                          90+ files\n|-- assets/                             Device photos and screenshots (5 files)\n|-- config/                             Config templates, no secrets (4 files)\n|-- docs/                               Step-by-step guides (18 files)\n|-- scripts/                            Python scripts for remote management (12 files)\n|-- utils/                              Device-side files deployed to phone (51 files)\n|-- .github/                            CI, templates, security policy, CoC\n|-- .env.example                        Environment variable template\n|-- .gitignore                          Excludes secrets, binaries, runtime data\n|-- CLAUDE.md                           AI session context (for Claude Code)\n|-- CONTRIBUTING.md                     Contribution guidelines\n|-- LICENSE                             MIT\n|-- Makefile                            30+ targets for device management\n|-- README.md                           This file\n+-- SECRETS.md                          Credential management reference\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull file listing\u003c/strong\u003e\u003c/summary\u003e\n\n```\nscripts/\n  connect.py                      SSH connection library + CLI\n  find_device.py                  Auto-discover device on local network\n  full_deploy.py                  12-step automated deployment\n  deploy_wrapper.py               Deploy TLS wrapper (idempotent)\n  device_info.py                  Full device diagnostic report\n  gateway.py                      Gateway management (start/stop/restart/logs)\n  change_model.py                 Switch LLM model (3 config locations)\n  edit_config.py                  Remote config editor (get/set/enable)\n  setup_voice.py                  Configure Whisper STT\n  install_scraping.py             Install web scraping stack\n  setup_knowledge.py              Create knowledge base on device\n  verify_resilience.py            8-phase resilience verification\n\nutils/                              (47 scripts + 2 shell configs + AGENT.md + README)\n  install.sh                      One-click Termux installer\n  picoclaw-wrapper.sh             TLS wrapper for the Go binary\n  boot-picoclaw.sh                Auto-start on boot (Termux:Boot)\n  watchdog.sh                     Cron watchdog: auto-restart all services every minute\n  network-recovery.sh             WiFi/mobile/ethernet fallback + interface tracking\n  log-rotate.sh                   Glob-based rotation + cache/backup/media cleanup\n  adb-connect.sh                  Smart ADB self-bridge with port auto-detection\n  adb-shell.sh                    Execute commands with ADB shell privileges\n  adb-enable.sh                   Re-enable ADB TCP if connection lost\n  detect-ip.sh                    Auto-detect device IP (5 methods)\n  notifications.sh                Read device notifications via ADB\n  ensure-unlocked.sh              Auto-unlock screen (wake + PIN)\n  wakeup.sh                       Wake / unlock cycle for scheduled tasks\n  ui-control.sh                   40+ UI automation commands\n  ui-auto.py                      Advanced UI automation (Python, XML parsing)\n  media-capture.sh                Photo/audio/screenshot/screenrecord\n  media-cleanup.sh                Auto-clean temp media files\n  media-tool.sh                   Unified wrapper: capture/analyze/cleanup\n  transcribe.sh                   STT: Azure Whisper -\u003e Groq cascade\n  tts-reply.sh                    TTS: Azure -\u003e Edge TTS (6 voices)\n  device-context.sh               AGENT.md generator with full device context\n  switch-model.sh                 Hot-swap LLM model (25 models)\n  scrape.sh                       Web scraper with method cascade\n  browser-tool.sh                 Headless Chromium: DOM, screenshots, PDF\n  qr-tool.sh                      QR code generation / scanning\n  image-tool.sh                   Image manipulation + OCR\n  pdf-tool.sh                     PDF text extraction + rendering\n  document-tool.sh                Universal document ingestion\n  remote-device.sh                USB OTG device control\n  auth-antigravity.sh             Google OAuth for Antigravity provider\n  auto-failover.sh                LLM provider health check + auto-switch on errors\n  grant-permissions.sh            Grant 44 permissions + 40 appops (from PC)\n  ssl-certs.sh                    System-wide SSL_CERT_FILE export\n  rag-tool.sh                     RAG store: BM25 + Gemini embeddings + RRF\n  memory-ingest.sh                Gateway log -\u003e RAG ingest cron\n  context-inject.sh               Inject retrieved memory into agent context\n  cost-tracker.sh                 Per-provider token/cost accounting\n  audit-log.sh                    Structured audit trail for every action\n  code-run.sh                     Polyglot code runner (16+ languages)\n  workflow.sh                     YAML-defined multi-step workflows\n  agent-self.sh                   Agent self-modification (personality/capability/snapshot)\n  channels-tool.sh                Live channel config (Telegram/WhatsApp/Discord/...)\n  cloudflare-tool.sh              Cloudflare Tunnel daemon (proot workaround)\n  system-tool.sh                  backup/restore/upgrade/pkg/services/health\n  webhook-server.py               Flask server v3: honeypot, HMAC, Bearer, CF Access, tiered rate limits, auto-ban\n  webhook-manage.sh               Full CRUD for /c/\u003cname\u003e routes/forms from chat\n  form-handler.sh                 Universal form handler: JSONL + RAG + notif + Telegram\n  bashrc / bash_profile           Shell configuration\n  AGENT.md                        Agent persona (static reference copy)\n```\n\n\u003c/details\u003e\n\n---\n\n## Security\n\n\u003e **Important**: Never commit API keys, tokens, passwords, or PINs. All secret files are git-ignored and use `chmod 600`.\n\nSee [SECURITY.md](.github/SECURITY.md) for the security policy and vulnerability reporting.\n\n| Control | Implementation |\n|---------|---------------|\n| API keys | Stored only in `security.yml` (`chmod 600`), never in `config.json` |\n| Gateway | Bound to `127.0.0.1` only (not exposed to network) |\n| SSH | `MaxAuthTries 3`, no empty passwords, keepalive 120s |\n| Scripts | `chmod 700` (owner-only execution) |\n| ADB | Localhost-only self-bridge, authorized keys required |\n| Credentials guide | [SECRETS.md](SECRETS.md) |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, [CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md) for community standards.\n\n---\n\n## Support\n\nSee [SUPPORT.md](.github/SUPPORT.md) for help, diagnostics, and contact information.\n\n---\n\n## Tech Stack\n\n| Layer | Technology | Role in this project |\n|-------|-----------|---------------------|\n| **AI Runtime** | [Go](https://go.dev) | PicoClaw binary (aarch64, 28 MB) |\n| **Automation** | [Python](https://python.org) | 13 remote management scripts (paramiko SSH) |\n| **MCP Servers** | [Node.js](https://nodejs.org) / [TypeScript](https://typescriptlang.org) | 4 MCP servers (146 tools) |\n| **Device Scripts** | [Bash](https://www.gnu.org/software/bash/) | 47 device-side scripts (Termux) |\n| **Cloud LLM** | [Azure OpenAI](https://azure.microsoft.com/en-us/products/ai-services/openai-service), [Google AI Studio](https://aistudio.google.com), [Ollama](https://ollama.com) | GPT-4o, Gemini, DeepSeek, 25+ models |\n| **Voice** | [Azure AI Speech](https://azure.microsoft.com/en-us/products/ai-services/ai-speech) + [Groq](https://groq.com) | STT (Whisper) + TTS (6 voices) |\n| **Messaging** | [Telegram Bot API](https://core.telegram.org/bots/api) | Long-polling gateway |\n| **CI/CD** | [GitHub Actions](https://github.com/features/actions) | Lint, validate, secret scan |\n| **Platform** | [Android](https://developer.android.com) / [Termux](https://termux.dev) | Linux on mobile |\n\n---\n\n## Credits\n\n- **[PicoClaw](https://github.com/sipeed/picoclaw)** by [Sipeed](https://sipeed.com) -- the AI assistant framework (MIT licensed)\n- **[Termux](https://termux.dev)** -- terminal emulator and Linux environment for Android\n- **[PixelOS](https://pixelos.net)** -- the custom ROM running on the device\n\n---\n\n## License\n\nThis dotfiles repository is licensed under [MIT](LICENSE). PicoClaw itself is [MIT-licensed](https://github.com/sipeed/picoclaw/blob/main/LICENSE) by Sipeed.\n\n\u003e This project is not affiliated with, endorsed by, or sponsored by Sipeed, Google, Microsoft, Telegram, Groq, or any other company mentioned. All trademarks belong to their respective owners. Cloud API usage is subject to each provider's terms of service and pricing. Free tiers may have rate limits or usage caps.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://carrillo.app\"\u003ecarrillo.app\u003c/a\u003e\n  \u0026nbsp;\u0026middot;\u0026nbsp;\n  \u003ca href=\"https://linkedin.com/in/carrilloapps\"\u003eLinkedIn\u003c/a\u003e\n  \u0026nbsp;\u0026middot;\u0026nbsp;\n  \u003ca href=\"https://t.me/carrilloapps\"\u003eTelegram\u003c/a\u003e\n  \u0026nbsp;\u0026middot;\u0026nbsp;\n  \u003ca href=\"https://github.com/carrilloapps\"\u003eGitHub\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarrilloapps%2Fpicoclaw-dotfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarrilloapps%2Fpicoclaw-dotfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarrilloapps%2Fpicoclaw-dotfiles/lists"}