Table of Contents

• Quick Start
• Features
• Supported Distributions
• Overview
• Screenshots
• Architecture
• Installation
• Updating
• Usage
• Use Cases
• Security & Privacy
• Components & Sources
• Troubleshooting
• Contributing
• License
• Author
• Support

Quick Start

[!Important] Before you start: install and run Shizuku first. If you're new to AndroSH, read the full Installation section below - it covers Shizuku setup and troubleshooting.

# In Termux
apt update && apt install -y python git
git clone --depth 1 https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH
pip install -r requirements.txt
python main.py install

androsh setup demo --distro debian --type stable
androsh launch demo

Features

• Multi-distro: run several Linux distributions side by side (Arch, Fedora, Alpine, Debian, Ubuntu, Kali, Void, Manjaro, Chimera, openSUSE)
• ADB/Shizuku-powered Linux: run full Linux distributions through Android's elevated Shell layer, with direct Android system integration - no root required
• SQLite-backed: fast, reliable tracking of your environments
• Isolated: each Linux environment runs through PRoot with userspace filesystem/process isolation
• GUI support: works with Termux:X11 for a full desktop environment - setup guide

Supported Distributions

Every distribution above ships from a verified rootfs source and runs in an isolated proot environment - no root required.

Overview

AndroSH lets you deploy and manage multiple full Linux distributions on Android by running PRoot through the ADB/Shizuku execution layer. This provides elevated Android-side execution without root while retaining direct Android system integration from inside the Linux environments.

Screenshots

Architecture

Android Device → ADB/Shizuku Execution Context→ Proot Virtualization → Linux Environment(s)

graph TD
    A[Android Device] --> B[ADB / Shizuku]
    B --> C[Android Shell Execution Context]
    C --> D[PRoot]

    D --> E[Alpine]
    D --> F[Debian]
    D --> G[Ubuntu]
    D --> H[Kali NetHunter]

    E --> I[Android System Integration]
    F --> I
    G --> I
    H --> I

    I --> K[Android Command Execution]
    I --> L[Android Filesystem Access]
    I --> M[Android Network Access]

    style D fill:#FF6B00,color:white
    style I fill:#4CAF50,color:white

From inside any distro, you can reach into the Android system directly:

# List installed Android packages
pm list packages -f

# Kernel info
cat /proc/version

# Android system properties
getprop | grep version

# Network routes
ip route show

Installation

Requirements

• Android device with Shizuku installed and running
• Python 3.8+
• Termux or a compatible terminal emulator
• At least 2 GB free storage

Setup

# Install prerequisites in Termux
apt update && apt install -y python git

# Get AndroSH
git clone --depth 1 https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH

# Install dependencies
pip install -r requirements.txt

# Make the `androsh` command available globally
python main.py install

[!Tip] when you run androsh setup, AndroSH automatically checks whether Shizuku is configured correctly and walks you through fixing it if not.

Updating

cd AndroSH
git pull
pip install -r requirements.txt

Usage

Deploy an environment

androsh setup production --distro debian --type stable

Launch it

androsh launch production
# You're now root inside the Debian environment
root@localhost:~# apt update && apt install python3 git

Manage environments

androsh list                       # See what's available to install
androsh lsd                        # See what's already installed
androsh clean production           # Free up space / remove temp files
androsh remove production --force  # Delete an environment

Manage distributions directly

androsh distro list                                              # List available distros
androsh distro info ubuntu                                       # Get details on a distro
androsh distro download alpine --type alpine-minirootfs --file alpine-edge.tar.gz

Full command reference

See AndroSH_Help.md for every command and flag, including verbosity control (--verbose / --quiet) and timestamp formatting (--time-style).

Use Cases

Learning Linux

androsh setup classroom --distro ubuntu --type stable
apt install gcc python3-dev git curl wget

Security research / penetration testing

androsh setup pentest --distro kali-nethunter --type full
apt install nmap metasploit-framework wireshark

Lightweight dev environments

androsh setup devops --distro alpine --type alpine-minirootfs
apk add build-base git nodejs npm docker-cli

On-the-go workstation

androsh setup field --distro debian --type stable
apt install vim tmux htop net-tools

Running several environments at once

androsh setup frontend --distro ubuntu -t stable
androsh setup backend --distro debian -t stable
androsh setup security --distro kali-nethunter -t nano
androsh lsd

Security & Privacy

• Android privilege boundary: Android-side operations run within the permissions available to the ADB/Shizuku execution context; no Android root is required.
• Process isolation: each environment runs sandboxed via proot
• Integrity checks: SHA-256 checksums validate every download
• No telemetry: zero data collection, everything stays local on your device
• Open source: every component is auditable

Components & Sources

Build pipelines: PRoot builder · BusyBox NDK sources · AndroSH core

All dependencies are traceable to their upstream sources and kept in sync with security updates.

Troubleshooting

Reset a broken environment

androsh setup <distro> --distro debian -t stable --resetup

Clean up temp files

Reinstall the global androsh command

cd AndroSH
python main.py install

Shizuku issues

• Confirm Shizuku is running and AndroSH is authorized in it
• If problems persist, reboot the device to restore the Shizuku service

Contributing

Contributions and security research are welcome. Current priority areas:

• Performance optimization
• Deployment tooling
• Security hardening

Set up a dev environment:

git clone https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

License

GPLv3 - free for commercial and research use.

Ahmed Al-Nassif

• GitHub: @ahmed-alnassif

Support

• Star the repo if you find it useful
• Open an issue to report bugs
• Suggest features or share how you're using AndroSH

Professional Linux environments in your pocket - without requiring Android root.