Getting Started with Ruuh

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.

Download Termux

Download Termux from F-Droid (recommended for Termux:API) or the Play Store.

F-Droid Play Store

Download Termux:API (Optional)

Install the Termux:API companion app for hardware access.

F-Droid

Installation

Once Termux and Termux:API are installed, open Termux and run a single command to set up everything automatically — Ubuntu environment, Ollama, and device skills.

$curl -fsSL https://raw.githubusercontent.com/perminder-klair/ruuh/main/scripts/setup.sh | bash

Step 1

Open Termux

Launch the Termux app on your Android device. You'll see a terminal prompt ready for input.

Step 2

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.

~ $ curl -fsSL https://raw.githubusercontent.com/perminder-klair/ruuh/main/scripts/setup.sh | bash

[1/3] Running ruuh-setup.sh...

Install Ollama + model? [Y/n] y

[2/3] Running ollama-setup.sh...

Install Termux API skills? [Y/n] y

[3/3] Running skills-setup.sh...

Full setup complete!

Step 3

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.

Step 4

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.

~ $ ruuh --ollama

Starting Ollama server...

Ollama ready

Starting Ruuh agent...

Web dashboard: http://localhost:3000

Ready. What do you need?

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

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

Step 1

Already installed?

If you chose “Y” when prompted during setup, Ollama is already installed with a model. Just run:

~ $ ruuh --ollama

Step 2

Install separately

If you skipped Ollama during setup, run the Ollama setup script manually. It installs Ollama, signs you in, and pulls a model.

~ $ curl -fsSL https://raw.githubusercontent.com/perminder-klair/ruuh/main/scripts/ollama-setup.sh | bash

Step 3

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.

To switch models, pull a new one and restart: ollama pull qwen3:1.7b then ruuh --ollama. Ruuh automatically uses the latest model you pulled.

Ollama supports both local and cloud models depending on your device. Run a cloud model with ollama pull qwen3:1.7b for on-device or ollama pull qwen3.5:cloud to run via Ollama's cloud infrastructure.

Useful Commands

Quick reference for common operations.

Start the agent

ruuh

Start with Ollama (local model)

ruuh --ollama

Switch to a different model

ollama pull qwen3:1.7b && ruuh --ollama

Edit agent settings

nano ~/agent/.pi/settings.json

Open web dashboard

http://localhost:3000

Log into Ubuntu manually

proot-distro login ubuntu

Run Pi manually inside Ubuntu

cd ~/agent && pi

Check battery (Termux API)

termux-battery-status

For the full list of commands, providers, and configuration options, see the pi-coding-agent documentation.

Troubleshooting

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.