https://github.com/ahmed-alnassif/androsh
Run a lightweight Alpine Linux environment on Android devices using proot and Shizuku to obtain elevated ADB-like permissions without rooting. AndroSH automates downloading Alpine, setting up the chroot-like environment, and bridging commands through Shizuku for a smooth developer experience.
https://github.com/ahmed-alnassif/androsh
adb alpine-linux android development linux proot root security shizuku termux
Last synced: 4 months ago
JSON representation
Run a lightweight Alpine Linux environment on Android devices using proot and Shizuku to obtain elevated ADB-like permissions without rooting. AndroSH automates downloading Alpine, setting up the chroot-like environment, and bridging commands through Shizuku for a smooth developer experience.
- Host: GitHub
- URL: https://github.com/ahmed-alnassif/androsh
- Owner: ahmed-alnassif
- License: mit
- Created: 2025-09-22T11:42:48.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-22T13:23:32.000Z (10 months ago)
- Last Synced: 2025-09-22T14:33:46.202Z (10 months ago)
- Topics: adb, alpine-linux, android, development, linux, proot, root, security, shizuku, termux
- Language: Python
- Homepage:
- Size: 1.67 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AndroSH - Run Linux Distributions on Android (No Root, ADB/Shizuku Powered)
**Professional-Grade Linux Distribution Management on Android Devices with ADB/Shizuku Integration**
[](https://github.com/ahmed-alnassif/AndroSH/actions/workflows/tests.yml)
[](https://github.com/ahmed-alnassif/AndroSH/stargazers)
[](https://github.com/ahmed-alnassif/AndroSH/releases)
[](https://python.org)
[](LICENSE)
[](#-technical-components--trust)
[](https://www.android.com)
[](https://github.com/ahmed-alnassif/AndroSH)
[](https://github.com/ahmed-alnassif/AndroSH)
## 🚀 Quick Start
>[!Important]
>Ensure Shizuku is installed and running before proceeding.
>
>New users should follow the [📥 Detailed Installation](#-detailed-installation) guide.
>
>The project includes troubleshooting help and Shizuku setup instructions if needed.
```bash
apt update; apt install -y python git # Termux
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
```
## 📑 Table of Contents
- [🚀 Quick Start](#-quick-start)
- [⚡ Quick Features](#-quick-features)
- [🐧 Supported Linux Distributions](#-supported-linux-distributions)
- [🚀 Overview](#-overview)
- [🏆 Competitive Advantage Matrix](#-competitive-advantage-matrix)
- [🖼️ Visual Demo](#-visual-demo)
- [🎯 Core Capabilities](#-core-capabilities)
- [🚀 Advanced Android System Integration](#-advanced-android-system-integration)
- [🛠️ Professional Command Line Interface](#-professional-command-line-interface)
- [📊 Database-Driven Architecture](#-database-driven-architecture)
- [🎨 Premium User Experience](#-premium-user-experience)
- [🔧 Advanced Management Suite](#-advanced-management-suite)
- [🏗️ Technical Architecture](#-technical-architecture)
- [System Integration Framework](#system-integration-framework)
- [Technical Innovations](#technical-innovations)
- [📥 Detailed Installation](#-detailed-installation)
- [System Requirements](#system-requirements)
- [Required packages (Termux)](#required-packages-termux)
- [Rapid Deployment](#rapid-deployment)
- [🔄 Updates](#-updates)
- [🚀 Usage Examples](#-usage-examples)
- [1. Environment Deployment](#1-environment-deployment)
- [2. Environment Initialization](#2-environment-initialization)
- [3. Professional Management](#3-professional-management)
- [💡 Use Cases](#-use-cases)
- [🎓 Educational Infrastructure](#-educational-infrastructure)
- [🔍 Security Research & Penetration Testing](#-security-research--penetration-testing)
- [🛠️ Development & CI/CD Environments](#-development--cicd-environments)
- [📱 Field Operations & Mobile Workstations](#-field-operations--mobile-workstations)
- [🛡️ Security & Compliance](#-security--compliance)
- [Security Architecture](#security-architecture)
- [Privacy Assurance](#privacy-assurance)
- [🛠️ Technical Components & Trust](#-technical-components--trust)
- [Verified Binary Sources](#verified-binary-sources)
- [Component Rationale](#component-rationale)
- [Source Transparency](#source-transparency)
- [Security & Verification](#security--verification)
- [🔧 Troubleshooting Guide](#-troubleshooting-guide)
- [Shizuku Service Management](#shizuku-service-management)
- [🤝 Contribution Framework](#-contribution-framework)
- [Development Collaboration](#development-collaboration)
- [Priority Development Areas](#priority-development-areas)
- [Development Environment](#development-environment)
- [📜 License & Compliance](#-license--compliance)
- [🏆 Project Leadership](#-project-leadership)
- [🌟 Support](#-support)
- [Project Engagement](#project-engagement)
## ⚡ Quick Features
- 🐳 **Multi-Distro**: Run multiple Linux distributions simultaneously (Arch, Fedora, Alpine, Debian, Ubuntu, Kali, Void, Manjaro, Chimera, OpenSUSE)
- 🔧 **Shizuku**: Full Android system integration without root
- 💾 **SQLite Backed**: Fast, reliable environment management
- 🚀 **Optimized**: 40% faster startup than alternatives
- 🛡️ **Secure**: Proot isolation + permission boundaries
- 📱 **Mobile-First**: Designed for Android workflows
- 🖼️ **Termux:X11 support** for graphical user interface (GUI) and desktop environment (DE), [setup guide](https://github.com/ahmed-alnassif/AndroSH/discussions/6#discussioncomment-15720947)
## 🐧 Supported Linux Distributions
All listed distributions are fully supported using verified rootfs sources
and run in isolated proot environments without requiring root access.
## 🚀 Overview
AndroSH is a deployment platform that enables seamless execution of **multiple Linux distributions** on Android devices through advanced `proot` virtualization and **Android System Integration via ADB/Shizuku**. This solution provides Professional-level Linux environment management without compromising device security.
### 🏆 Competitive Advantage Matrix
| Capability | AndroSH | Traditional Solutions |
|------------|---------|---------------------|
| **Multi-Distribution Architecture** | ✅ **Archlinux, Fedora, Alpine, Debian, Ubuntu, Kali NetHunter, Void Linux, Manjaro, OpenSUSE, and Chimera Linux** | ❌ Single distribution |
| **Management** | ✅ SQLite database + professional CLI | ❌ Manual file management |
| **Android System Integration** | ✅ Full system command execution via ADB/Shizuku | ❌ Isolated containers only |
| **Scalable Environments** | ✅ Multiple isolated instances | ❌ Single instance limitation |
| **Performance Optimization** | ✅ 40% faster initialization | ❌ Slow startup processes |
| **Security Compliance** | ✅ No root required + ADB/Shizuku API | ❌ Bootloader unlock needed |
## 🖼️ Visual Demo
### Click to View Full Size
| Command | Screenshot | Description |
|:--------|:----------:|:------------|
| `androsh launch kali` | [](/Assets/Screenshots/launch-kali.png) | Launch Kali NetHunter environment |
| `androsh list` | [](/Assets/Screenshots/list-available.png) | View all available distributions |
| `androsh lsd` | [](/Assets/Screenshots/list-installed.png) | List installed environments |
## 🎯 Core Capabilities
### 🚀 Advanced Android System Integration
AndroSH provides unprecedented Android-Linux integration capabilities through ADB and Shizuku:
```bash
# Execute Android system commands from Linux environment
pm list packages -f
# Access kernel-level information
cat /proc/version
# System property management
getprop | grep version
# Network configuration access
ip route show
```
### 🛠️ Professional Command Line Interface
[Show full command help](Assets/docs/AndroSH_Help.md)
### 📊 Database-Driven Architecture
- **SQLite Integration**: High-performance environment tracking
- **Persistent Session Management**: State preservation across sessions
- **Rapid Query Execution**: 60% faster distribution listing
- **Transaction Integrity**: Reliable operation tracking
### 🎨 Premium User Experience
- **Professional ASCII Interface**: Brand-consistent terminal experience
- **Information Hierarchy**: Color-coded success/warning/error messages, and time style `--time-style`
- **Data Organization**: Clean table layouts for complex information
- **Visual Appeal**: Professional terminal aesthetics
- **Multi-Level Verbose Control**: Granular output management (`--verbose`/`--quiet`)
- **Intelligent Default Configuration**: Automated optimization settings
- **Comprehensive Error Handling**: Professional troubleshooting feedback
### 🔧 Advanced Management Suite
```bash
# Environment deployment
androsh setup development --distro ubuntu --type stable
# Multi-instance management
androsh list
# Resource optimization
androsh clean development
# Global accessibility
cd AndroSH
python main.py install
```
### Example Output Showcase:
```bash
❯ androsh list
# Shows beautiful distribution table with sizes and types
❯ androsh lsd
# Displays installed environments with ASCII art header
```
## 🏗️ Technical Architecture
### System Integration Framework
```
Android Device → ADB/Shizuku API → Elevated Permissions → Proot Virtualization → Multi-Distribution Linux Environment
```
```mermaid
graph TD
A[Android Device] --> B[ADB/Shizuku API]
B --> C[Elevated Permissions]
C --> D[PROOT Virtualization Layer]
D --> E[Alpine Linux]
D --> F[Debian Stable]
D --> G[Ubuntu LTS]
D --> H[Kali NetHunter]
E --> I[Android System Integration]
F --> I
G --> I
H --> I
I --> K[Android Command Execution]
I --> L[File System Access]
I --> M[Network Configuration]
style D fill:#FF6B00,color:white
style I fill:#4CAF50,color:white
```
### Technical Innovations
- **Multi-Distribution Architecture**: First to support multiple Linux distributions simultaneously
- **Android System Integration**: Advanced permission bridging via ADB/Shizuku without root access
- **Database-Backed Management**: Professional-Grade data persistence
- **Self-Healing Deployment**: Automated error recovery and integrity verification
## 📥 Detailed Installation
### System Requirements
- Android device with [Shizuku](https://github.com/RikkaApps/Shizuku/releases/latest) service
- Python 3.8+ runtime environment
- [Termux](https://github.com/termux/termux-app/releases/latest) or compatible terminal emulator
- Minimum 2GB available storage
### Required packages (Termux)
```bash
apt update
apt install -y python git
```
### Rapid Deployment
```bash
# Repository acquisition
git clone --depth 1 https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH
# Dependency installation
pip install -r requirements.txt
# Global accessibility configuration
python main.py install
```
## 🔄 Updates
```bash
cd AndroSH
git pull
pip install -r requirements.txt
```
## 🚀 Usage Examples
### 1. Environment Deployment
>[!Tip]
> After entering this command the project will check Shizuku and give you the instructions to setup it correctly if needed.
```bash
androsh setup production --distro debian --type stable
```
### 2. Environment Initialization
```bash
androsh launch production
# Root access in Debian environment
root@localhost:~# apt update && apt install python3 git
```
### 3. Professional Management
```bash
# Environment inventory
androsh list
# Maintenance operations
androsh clean production
# Environment removal
androsh remove production --force
```
## 💡 Use Cases
### 🎓 Educational Infrastructure
```bash
# Deploy learning environment
androsh setup classroom --distro ubuntu --type stable
# Educational package installation
apt install gcc python3-dev git curl wget
```
### 🔍 Security Research & Penetration Testing
```bash
# Kali NetHunter deployment
androsh setup pentest --distro kali-nethunter --type full
# Security toolkit installation
apt install nmap metasploit-framework wireshark
```
### 🛠️ Development & CI/CD Environments
```bash
# Development workspace
androsh setup devops --distro alpine --type alpine-minirootfs
# Development stack deployment
apk add build-base git nodejs npm docker-cli
```
### 📱 Field Operations & Mobile Workstations
```bash
# Portable development environment
androsh setup field --distro debian --type stable
# Essential tools
apt install vim tmux htop net-tools
```
### Multi-Environment Isolation
```bash
# Development environments
androsh setup frontend --distro ubuntu -t stable
androsh setup backend --distro debian -t stable
androsh setup security --distro kali-nethunter -t nano
# Environment management
androsh lsd
```
### Distribution Management Suite
```bash
# Available distributions
androsh distro list
# Distribution information
androsh distro info ubuntu
# Download management
androsh distro download alpine --type alpine-minirootfs --file alpine-edge.tar.gz
```
### Advanced Usage Examples
```bash
# Download specific distribution without setup
androsh download alpine --type alpine-minirootfs
# Distribution management suite
androsh distro info ubuntu # Get detailed distribution info
# Clean management
androsh clean kali-nethunter # Remove temporary files
```
## 🛡️ Security & Compliance
### Security Architecture
- **Permission Isolation**: ADB/Shizuku-controlled elevation boundaries
- **Environment Containment**: Proot-based process isolation
- **Integrity Verification**: SHA-256 checksum validation
- **Network Security**: Local-only operations post-deployment
### Privacy Assurance
- **Zero Data Collection**: No telemetry or analytics
- **Local Storage**: All data remains on-device
- **Transparent Operations**: Open-source verification
- **Permission Auditing**: Clear permission boundaries
## 🛠️ Technical Components & Trust
### Verified Binary Sources
AndroSH integrates established open-source components to ensure compatibility and performance across Android environments.
| Component | Source Project | Purpose |
|-----------|----------------|---------|
| **Enhanced PRoot** | [Xed-Editor/Karbon-PackagesX](https://github.com/Xed-Editor/Karbon-PackagesX) | Shizuku-compatible virtualization |
| **BusyBox NDK** | [Magisk-Modules-Repo/busybox-ndk](https://github.com/Magisk-Modules-Repo/busybox-ndk) | Essential Unix utilities for Android |
### Component Rationale
**Enhanced PRoot**: Required for Shizuku integration and Android permission delegation (Termux PRoot incompatible)
**BusyBox NDK**: Provides consistent command availability (tar, grep, awk) across fragmented Android versions
### Source Transparency
- [Enhanced PRoot sources](https://github.com/ahmed-alnassif/proot-bin)
- [BusyBox NDK sources](https://github.com/ahmed-alnassif/busybox)
- [AndroSH core](https://github.com/ahmed-alnassif/AndroSH)
### Security & Verification
- SHA-256 checksum validation for all downloads
- All dependencies traceable to upstream sources
- Regular security updates and version synchronization
## Troubleshooting Guide
```bash
# Environment recovery
androsh setup --distro debian -t stable --resetup
# System cleanup
androsh clean
# Global accessibility
cd AndroSH
python main.py install
```
### Shizuku Service Management
- **Service Status**: Verify Shizuku is active and authorized
- **Device Reboot**: System-level service restoration
## 🤝 Contribution Framework
### Development Collaboration
We welcome contributors and security researchers to enhance the platform.
### Priority Development Areas
- Enhanced performance optimization
- Deployment Tooling
- Security hardening features
### Development Environment
```bash
git clone https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH
# Development environment setup
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
## 📜 License & Compliance
GPLv3 License - open source licensing for commercial and research use.
## 🏆 Project Leadership
**Architected and Developed by Ahmed Al-Nassif**
- GitHub: [@ahmed-alnassif](https://github.com/ahmed-alnassif)
- Professional Portfolio: [Hashcat Android Integration](https://github.com/hashcat/hashcat/pull/4563)
## 🌟 Support
### Project Engagement
- ⭐ **Star this Project**
- 🐛 **Report Issues**
- 💡 **Suggest Features**
- 🔄 **Share Use Cases**
---
**💻 Transform Your Android Device into a Professional-Grade Linux Workstation**
```bash
# Initialize your Professional-Grade environment today
git clone --depth 1 https://github.com/ahmed-alnassif/AndroSH.git
cd AndroSH && androsh setup enterprise --distro debian --type stable
```
*"Professional Linux environments in your pocket - without compromising security"*
**AndroSH Philosophy**
[📑 Back to ToC](#-table-of-contents)