Getting Started
Everything you need to install and run Ruuh on your Android device. The entire process takes about five minutes.
Prerequisites
Before you begin, make sure you have the following.
Android Device
Any Android phone or tablet running Android 7+.
Termux from F-Droid
Download Termux from F-Droid — the Play Store version is outdated and won't work.
DownloadAPI Key (optional)
An OpenAI or Anthropic API key for cloud models, or use Ollama for fully local/offline.
Installation
Run a single command to set up everything automatically — Termux environment, Ollama, and device skills.
curl -fsSL https://raw.githubusercontent.com/perminder-klair/ruuh/main/scripts/setup.sh | bashOpen Termux
Launch the Termux app on your Android device. You'll see a terminal prompt ready for input.
Run the Install Command
Paste the one-liner below into Termux. It runs one command with three steps — the Termux + Ubuntu environment installs automatically, then Ollama and Termux API skills each prompt Y/n so you can skip them.
Grant Storage Permission
During setup, Android will ask for storage permission. Grant it so Ruuh can store config files in Internal Storage > ruuh, accessible from any file manager or text editor.
Start Ruuh
Once the install finishes, type ruuh to launch the agent. Use ruuh --ollama to start with a local model via Ollama. It logs into the Ubuntu proot environment and starts pi-coding-agent from the shared config directory. A web dashboard starts automatically at localhost:3000 — open it in your device browser while the agent is running.
Configuration Files
Ruuh creates a set of Markdown files you can edit from any text editor on your phone. No terminal required.
AGENTS.md
Master workspace config — startup routine, memory structure, and how the agent behaves each session.
SOUL.md
Personality and behavioral guidelines — tone, communication style, and boundaries.
IDENTITY.md
The agent fills this in during its first conversation — name, creature type, vibe, and emoji.
USER.md
Profile of the human — name, pronouns, timezone, and contextual notes. Updated as the agent learns about you.
MEMORY.md
Persistent long-term memory across sessions. The agent writes here to remember decisions and context.
BOOTSTRAP.md
First-run ritual — guides the intro conversation. Deleted after the first session.
BOOT.md
Custom startup tasks the agent runs each session. Leave empty if unused.
HEARTBEAT.md
Periodic task scheduler for interval-based checks. Leave empty if unused.
TOOLS.md
Quick reference of available Termux API commands from installed skills.
File Locations
~/storage/shared/ruuh/~/agent/Internal Storage > ruuhTermux API Skills
Teach Ruuh how to use your Android device features. Skills are auto-discovered on startup — install once, use everywhere. If you skipped skills during setup or want to reinstall them, run the command below.
Requires the Termux:API companion app installed from F-Droid for hardware access. Both Termux and Termux:API must be installed from F-Droid — mixing Play Store and F-Droid versions causes signature mismatch errors.
curl -fsSL https://raw.githubusercontent.com/perminder-klair/ruuh/main/scripts/skills-setup.sh | bashtermux-device
Device hardware, sensors, and UI — battery status, brightness, torch, vibrate, volume, sensors, fingerprint, GPS location, WiFi, clipboard, notifications, dialogs, toasts, wake lock, wallpaper, and downloads.
termux-comms
Communication and media — SMS send & receive, contacts, call log, camera photos, microphone recording, text-to-speech, media playback, file sharing, storage picker, and calendar access.
termux-system
System integration and automation — job scheduling, infrared transmit, USB device access, NFC tag read/write, and hardware keystore crypto.
Using Ollama (Local Models)
Run AI models locally for full privacy and offline access. No API keys, no internet, no data leaving your device.
Already installed?
If you chose “Y” when prompted during setup, Ollama is already installed with a model. Just run:
Install separately
If you skipped Ollama during setup, run the Ollama setup script manually. It installs Ollama, signs you in, and pulls a model.
How it works
ruuh --ollama starts the Ollama server, launches the agent with the local model, and stops Ollama when you exit. No API keys needed.
Useful Commands
Quick reference for common operations.
ruuhruuh --ollamahttp://localhost:3000proot-distro login ubuntucd ~/agent && pitermux-battery-statusTroubleshooting
Common issues and how to fix them.
Storage permission not granted
Restart Termux after granting storage permission in Android settings, then re-run the setup script.
Ubuntu install fails or hangs
Check your internet connection. Run pkg update -y first, then try the setup script again.
ruuh command not found
The setup script may not have completed. Re-run the full install command from the top of this page.
Ollama connection refused
Make sure Ollama is running and accessible. If it's on another machine, ensure the network allows the connection and OLLAMA_HOST is set correctly.
Config files not showing in file manager
Look for Internal Storage > ruuh in your Android file manager. The files are plain Markdown (.md) and can be opened with any text editor.