https://github.com/ravindu644/Ubuntu-Chroot
Run Ubuntu 24.04 on Android With full Hardware Access and pure namespace isolation..!
https://github.com/ravindu644/Ubuntu-Chroot
chroot docker docker-on-android kernelsu magisk nethunter samsung ubuntu
Last synced: 3 days ago
JSON representation
Run Ubuntu 24.04 on Android With full Hardware Access and pure namespace isolation..!
- Host: GitHub
- URL: https://github.com/ravindu644/Ubuntu-Chroot
- Owner: ravindu644
- License: mit
- Archived: true
- Created: 2025-10-29T23:11:53.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-12-08T17:44:48.000Z (8 months ago)
- Last Synced: 2026-03-05T19:38:01.398Z (5 months ago)
- Topics: chroot, docker, docker-on-android, kernelsu, magisk, nethunter, samsung, ubuntu
- Language: Python
- Homepage: https://t.me/SamsungTweaks
- Size: 6.39 MB
- Stars: 106
- Watchers: 4
- Forks: 17
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-android-root - Ubuntu Chroot - Run Ubuntu 24.04 on Android With full Hardware Access and pure namespace isolation. `FOSS` `[M]` `[K]` (Developer Tools / Install and Run Linux Environments)
README
[](https://github.com/ravindu644/ubuntu-chroot/releases/latest)
[](https://t.me/SamsungTweaks)
[](./LICENSE)
[](#requirements)
[](#why-this-is-different)
---
# 🟠 Ubuntu-Chroot
A comprehensive Android Linux environment featuring **Ubuntu 24.04** with a built-in WebUI Control Panel, Beautiful desktop environment, advanced namespace isolation, and in-built development tools for a seamless Linux desktop experience on Android - **with full hardware access and x86_64 emulation**.
#### Quick Navigation
- [Requirements](#requirements)
- [Why This Is Different](#why-this-is-different)
- [Installation](#installation)
- [Get Started](#usage)
- [Access the GUI](#gui)
- [Experimental Features](#experimental-features)
- [Kernel Requirements (Optional)](#kernel-requirements)
- [Running Docker inside Chroot](#docker)
- [To-Do](#to-do)
- [Known issues](#known-issues)
- [Credits](#credits)
- Android device with arm64 architecture
- Unlocked bootloader
- Rooted with APatch/KernelSU
- Magisk is not supported due to **TTY issues starts with version 29**. If using Magisk, use a version below v29.
- [Custom Kernel with these configs enabled (optional)](#kernel-requirements)
**Advanced Namespace Isolation**
- Utilizes Linux namespaces (mount, PID, UTS, IPC) for true namespace isolation. Unlike basic chroot setups, this creates separate filesystem mounts, process IDs, hostnames, and IPC spaces - preventing interference between the chroot and Android host.[1]
Process isolation demonstration
Illustration of isolated namespaces
> [!TIP]
>
> **Why Namespaces Matter:**
>
> Traditional chroot only changes the root directory. **Namespaces create isolated environments,** ensuring processes inside the chroot cannot see or affect host system processes, hostnames, or IPC resources.
>
> This allows full Linux services to run without conflicts, security risks, or performance loss.
**Full Hardware Access**
- Complete access to all hardware features of your Android device, including WiFi adapters, ADB, Odin, and more.[2]
Using an external WIFI adapter inside chroot
Example tools running with full device access
**x86_64 Emulation**
- Preconfigured x86_64 emulation enables you to run x86_64 applications and binaries directly on your Android device with full hardware access.[3]
Odin4 x86_64 running with full hardware access
Rebooting a phone in Download Mode using x86_64 Odin4 on an ARM64 device
**"It Just Works" Philosophy**
- No complex terminal commands required. The desktop environment starts automatically when the chroot launches, and most developer tools are preconfigured and ready to use out of the box.
**Containerization Ready**
- When you flash the module, it extracts the Ubuntu rootfs to `/data/local/ubuntu-chroot`, which the backend uses as the installed rootfs.
- Under **Experimental Features** in the WebUI, you can migrate your directory-based chroot to an ext4 sparse image, containerizing your environment into a single `.img` file.
- The Linux environment runs on an ext4 image outside Android partitions, benefiting from improved I/O, caching, and flexibility.
- You can freely shrink, grow, and FSTRIM your sparse image after migration.
- A sparse image can be created at any size (even 1TB) but only consumes real storage as data is written - an efficient storage method for your Linux environment.
**Seamless Desktop Experience**
📸 Desktop Screenshots (click to expand)
Landscape mode
Portrait mode
- A complete Linux desktop experience on Android, capable of running GUI applications smoothly.[4]
**Forward Chroot Traffic to Any Network Interface**
- Native WiFi hotspot functionality supporting both 2.4GHz and 5GHz bands. Automatically configures `hostapd` and DHCP services within the chroot environment for instant `localhost` sharing.
- If the Native WiFi hotspot didn't work for you, you still have a separated menu to forward all the chroot traffic to any desired network interface. (e.g., USB Tethering/WiFi Hotspot created using Android userspace)
> **💡 Example**:
>
> Use the GUI running on your phone and project it to another large screen with near-zero latency.
**Incremental OTA Updates**
- Version-tracked incremental updates preserve user data and configurations across upgrades, eliminating the need for full reinstallation.
**Backup and Restore**
- Back up your chroot environment to a compressed archive and restore it later, or transfer it to another device.
**Post-Exec Scripts and "Run on Boot"**
- Define scripts to run automatically when the chroot boots.
> **💡 Example**:
>
> Enable "Run on boot" and reboot your phone - the chroot will automatically start (even while locked), executing your post-exec script so you can host bots, SSH, or background services effortlessly.
**Modern WebUI**
- Access and manage your chroot environment from KernelSU/APatch in-built WebUI.
WebUI screenshots
1. Download the latest release from [GitHub releases](https://github.com/ravindu644/ubuntu-chroot/releases)
2. Flash the ZIP file using APatch/KernelSU managers
3. Reboot your device
1. Access the chroot control panel using APatch/KernelSU's built-in WebUI
2. On the first installation, you have to set up your user account to access GUI functionality (VNC/RDP):
- Start the chroot from the WebUI
- Copy the login command
- Paste it in Termux and complete the user account setup
- Return to the WebUI and click "Restart" to apply changes
3. You can now log in as the created user via:
- **CLI**: Copy the login command and paste it in Termux or any other terminal emulator, including ADB Shell
- **GUI (VNC)**: Use the [AVNC Android app](https://github.com/gujjwal00/avnc) (recommended for best performance)
- **GUI (RDP)**: Uncomment the `# start_xrdp` line in the Post-exec Script from the WebUI and restart the chroot
> **Note**: There is currently no perfect RDP app for Android. Please create an issue if you find a better option.
Once you've set up your user account following the [Get Started](#usage) section, **the XFCE Desktop Environment will automatically start when you start the chroot from the WebUI - no need to type anything in the terminal !**
The default method to access the GUI is using the VNC protocol with a VNC viewer application.
**Recommended VNC Clients:**
- **Android**: [AVNC](https://github.com/gujjwal00/avnc)
- **Windows**: [TigerVNC](https://github.com/TigerVNC/tigervnc)
- **Linux**: [TigerVNC](https://github.com/TigerVNC/tigervnc)
### Local Access (Same Device)
**Connection Settings for AVNC (Android):**
- **Host**: `localhost`
- **Port**: `5901`
- **Username**: Your chroot user account username
- **Password**: Your chroot user account password
### Remote Access (External Device)
To access the GUI from a different device (e.g., a computer or tablet), **you need to forward the chroot traffic to a network interface**. There are two methods available:
#### Method 1: Built-in Hotspot
This method creates a WiFi hotspot directly from the chroot environment:
1. Open the WebUI and navigate to the **Hotspot Configuration** option
2. Configure your hotspot settings (Upstream, SSID, password, band, channel)
3. Click **Start Hotspot**
4. Connect your external device to the created hotspot
5. Install a VNC client on the external device
6. Use the IP address and port displayed in the console log along with your login credentials to connect
#### Method 2: USB Tethering (Fastest)
If the built-in hotspot doesn't work, or you need the **lowest latency experience**, you can use Android's USB Tethering feature:
1. Open the WebUI and click the **Refresh** button
2. Navigate to **Forward Chroot Traffic** and note the currently available network interfaces
3. Connect your phone to the target device using a USB cable
4. Enable **USB Tethering** on your Android device
5. Return to the WebUI, click **Refresh** again, and navigate to **Forward Chroot Traffic**
6. You should now see a new network interface that wasn't present before
7. Select the new network interface and click **Start Forwarding**
8. Use the IP address and port displayed in the console log along with your login credentials to connect
> [!TIP]
>
> The IP address will be displayed in the WebUI console after starting the hotspot or forwarding.
>
> Look for messages like `Gateway IP` to determine the value for `Host` required for the VNC client. For VNC, the port is always `5901`.
### Advanced: RDP Access
For advanced users who prefer RDP over VNC:
1. Open the WebUI and navigate to **Options** → **Post-exec Script**
2. Remove the comment (`#`) from the `start_xrdp` line
3. Restart the chroot from the WebUI
4. Use an RDP client to connect using the same connection method as VNC (hotspot or USB tethering)
> **Note**: There is currently no perfect RDP app for Android. VNC is recommended for the best experience.
**Sparse Image Mode Installation**
- Edit the [experimental.conf](./experimental.conf) file before installation:
- Set `SPARSE_IMAGE=true`
- Define the image size in GB using `SPARSE_IMAGE_SIZE`
**Converting to Sparse Image**
- You can convert your existing directory-based installation to an isolated ext4 sparse image from the WebUI under **Experimental Features**.
**Downloading Firmware**
- If you want to download and decompress firmware files (useful for installing WIFI firmware without installing random Magisk modules from the internet), run the following command inside the chroot:
```bash
sudo download-firmware
```
This script will install the `linux-firmware` package, decompress all `.zst` firmware archives, and update symlinks to point to the decompressed files. The script creates a marker file to prevent re-running, so it's safe to execute multiple times.
- After downloading the firmware, restart the chroot from the WebUI to apply the changes.
The following features are currently not planned for implementation by the maintainer, but **Pull Requests are always welcome** if you figure out a way to implement them:
- Audio forwarding in RDP
- Termux-independent GPU acceleration
## 🐛 Known issues
1. **Snap and Flatpak support**
- Snap and Flatpak are not native applications like those we install from `.deb`, `.AppImage`, or APT. They are containerized applications running in an isolated environment without any privileged access.
- To create those isolated, containerized applications, your Android kernel must have support for various filesystems and drivers, as well as kernel patches to enable unprivileged user namespaces.
- Even if you somehow compiled a custom kernel with all the required features enabled, the functionality is not guaranteed because we are creating an isolated environment within an already isolated environment.
- Related issue: [#1](https://github.com/ravindu644/Ubuntu-Chroot/issues/4)
2. **`Error: sh: [5]: /system/bin/su: No such file or directory` in KernelSU LKM mode/Kernels with KernelSU KProbe Hooks**
- This is a **known limitation in KernelSU** when using **LKM mode** or **GKI kernels with KProbe hooks** or **non-GKI Kernels without proper 32-bit support hooks**.
- This occurs because official **KernelSU dropped support for 32-bit applications** starting from versions above v0.9.2, and all KernelSU forks have inherited this limitation.
- **This causes all 32-bit applications to lose their ability to detect root**, including ADB shell on devices with dual ABI support, Nethunter terminal, Root explorer, etc.
- **The only fix for this issue is to use a proper kernel with KernelSU manual hooks that support 32-bit applications**, instead of using LKM mode or GKI kernels with KProbe hooks.
- This error does not originate from this project; it's coming from KernelSU's side.
- More info: [telegram](https://t.me/Samsung_Tweaks/89289), [Github issue created by me in 2024](https://github.com/tiann/KernelSU/issues/2095), [Another similar issue](https://github.com/KernelSU-Next/KernelSU-Next/issues/250)
**These configurations are optional**, as 80% are enabled in Android by default. However, to ensure everything works perfectly and achieve maximum potential from this project, these kernel configs should be enabled.
#### 01. Core Namespace Support (Required for Isolation)
```Makefile
CONFIG_NAMESPACES=y
CONFIG_PID_NS=y
CONFIG_UTS_NS=y
CONFIG_MNT_NS=y
CONFIG_IPC_NS=y
```
#### 02. Essential Filesystems for Hardware Access
```Makefile
CONFIG_DEVTMPFS=y
CONFIG_PROC_FS=y
CONFIG_SYSFS=y
```
#### 03. Running x86_64 Binaries Natively
```Makefile
CONFIG_BINFMT_MISC=y
CONFIG_BINFMT_SCRIPT=y
CONFIG_BINFMT_ELF=y
```
#### 04. GUI Applications Support
```Makefile
# IPC mechanisms (required by many apps and daemons)
# KDiskMark and Brave Browser will fail without these
CONFIG_SYSVIPC=y
CONFIG_SYSVIPC_SYSCTL=y
CONFIG_PROC_SYSCTL=y
CONFIG_POSIX_MQUEUE=y
```
#### 05. Docker Support in Chroot
```Makefile
CONFIG_CGROUPS=y
CONFIG_CGROUP_DEVICE=y
CONFIG_MEMCG=y
```
Complete Kernel Configuration (click to expand)
```Makefile
# Ubuntu Chroot Kernel Configuration
# Copyright (C) 2025 ravindu644
# Note: A custom kernel is not required, but most features
# will be limited without these configurations.
# CRITICAL: Essential for basic chroot functionality
# Core namespace support (required for isolation)
CONFIG_NAMESPACES=y
CONFIG_PID_NS=y
CONFIG_UTS_NS=y
CONFIG_IPC_NS=y
# Essential filesystems
CONFIG_PROC_FS=y
CONFIG_SYSFS=y
CONFIG_DEVTMPFS=y
CONFIG_TMPFS=y
CONFIG_EXT4_FS=y
# QEMU support
CONFIG_BINFMT_MISC=y
CONFIG_BINFMT_SCRIPT=y
CONFIG_BINFMT_ELF=y
# Terminal support (required for login)
CONFIG_UNIX98_PTYS=y
CONFIG_TTY=y
CONFIG_DEVPTS_FS=y
# Basic networking
CONFIG_NET=y
CONFIG_INET=y
CONFIG_UNIX=y
# Threading support
CONFIG_FUTEX=y
# File operations
CONFIG_FILE_LOCKING=y
# IMPORTANT: Common functionality requirements
# IPC mechanisms (required by many apps and daemons)
# KDiskMark and Brave Browser will fail without these
CONFIG_SYSVIPC=y
CONFIG_POSIX_MQUEUE=y
# Device management
CONFIG_DEVTMPFS_MOUNT=y
# Extended filesystem features
CONFIG_TMPFS_POSIX_ACL=y
CONFIG_TMPFS_XATTR=y
CONFIG_EXT4_FS_POSIX_ACL=y
CONFIG_EXT4_FS_SECURITY=y
# Control groups (essential for Docker)
CONFIG_CGROUPS=y
CONFIG_CGROUP_DEVICE=y
CONFIG_MEMCG=y
# Event handling
CONFIG_EPOLL=y
CONFIG_EVENTFD=y
CONFIG_SIGNALFD=y
CONFIG_TIMERFD=y
# File monitoring
CONFIG_INOTIFY_USER=y
# Security
CONFIG_SECCOMP=y
CONFIG_SECCOMP_FILTER=y
# Networking features
CONFIG_IPV6=y
CONFIG_PACKET=y
# Legacy PTY (for compatibility)
CONFIG_LEGACY_PTYS=y
CONFIG_LEGACY_PTY_COUNT=256
# OPTIONAL: Advanced features and specific use cases
# Advanced cgroup controllers
CONFIG_CGROUP_CPUACCT=y
CONFIG_CGROUP_SCHED=y
CONFIG_CGROUP_FREEZER=y
CONFIG_CGROUP_PIDS=y
CONFIG_MEMCG_SWAP=y
# Overlay filesystem (for Docker-like functionality)
CONFIG_OVERLAY_FS=y
# FUSE (for userspace filesystems like sshfs, AppImage)
CONFIG_FUSE_FS=y
# Firmware loading
CONFIG_FW_LOADER=y
CONFIG_FW_LOADER_USER_HELPER=y
CONFIG_FW_LOADER_COMPRESS=y
# Loop devices (for mounting disk images)
CONFIG_BLK_DEV_LOOP=y
# Async I/O (for database servers and high-performance apps)
CONFIG_AIO=y
# System control interface
CONFIG_PROC_SYSCTL=y
CONFIG_SYSVIPC_SYSCTL=y
```
## 🐳 Running Docker inside Chroot
> [!TIP]
> **Docker is already installed and configured by default,** so you don't need to do anything to install it.
**The quick way to verify if you can run Docker containers is to check if the "Devices Cgroups" are mounted.**
- If you see these logs in the console, then your device has minimal Docker support:
```
[INFO] Setting up minimal cgroups for Docker...
[INFO] Cgroup devices mounted successfully.
```
- Otherwise, there's no way to run Docker inside the phone unless you compile a custom kernel.
**Next,** verify if your `/data` partition is `ext4`.
- **If it is f2fs,** you **MUST** use the migrate feature from "Options -> Experimental Features -> Migrate to Sparse Image" so Docker can properly wire up OverlayFS on top of the ext4 mounted rootfs.
**After verifying your kernel supports Devices Cgroups and resolving any `ext4` filesystem issues, you need to start the Docker daemon using the command below.**
- Run this inside the chroot terminal: `sudo dockerd`
- If the Docker daemon started successfully, it should show something like this:
```
INFO[2025-12-08T16:59:04.981797971Z] Completed buildkit initialization
INFO[2025-12-08T16:59:05.016738894Z] Daemon has completed initialization
INFO[2025-12-08T16:59:05.017061663Z] API listen on /var/run/docker.sock
```
- If it failed, that means your kernel does not support running Docker even though the "Devices Cgroups" are available.
- In that case, you need to compile a custom kernel with all the required Docker configurations enabled.
**To verify Docker is fully functional,** you can run this command in a new terminal: `docker run -it hello-world`
**To run the Docker daemon whenever the chroot starts, you can modify the "Post-exec Script" from the WebUI by going into the "Options" menu.**
- To enable it, remove the comment from the beginning of the `dockerd > /dev/null 2>&1 &` line, like this:
Uncomment dockerd in post-exec
> [!NOTE]
> **Networking inside Docker**
>
> **For maximum compatibility,** we ship the pre-built rootfs with Docker networking features disabled and **force configured** to use **NAT** instead of creating Docker's own `docker0` network interface.
>
> You can modify this behavior by editing `/etc/docker/daemon.json` if needed.
>
> **Additionally,** every action you run with the `docker run` command will automatically use `docker run --net=host` via the `docker` function in [this script](./Docker/scripts/bashrc.sh), which tells Docker to use the host network for all networking tasks, including internet access.
> [!IMPORTANT]
>
> **Even if you have a custom kernel with all the necessary configurations enabled,** Docker still won't be able to create the `docker0` interface without flushing the existing iptables filter chains.
>
> **To do this,** first, you need to use `iptables-legacy` and `ip6tables-legacy`.
>
> Run these commands inside Ubuntu:
> ```
> update-alternatives --set iptables /usr/sbin/iptables-legacy
> update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
>```
> **Then,** run these commands to fix the Docker iptables issue:
> ```
> iptables -t filter -F
> ip6tables -t filter -F
>```
>
> **Now,** you can edit `/etc/docker/daemon.json` to use iptables and run `dockerd` to see if it works. Keep in mind this will only work if your kernel has the necessary kernel configurations enabled.
- [Ubuntu](https://ubuntu.com/) - The core
- [Kali NetHunter project](https://gitlab.com/kalilinux/nethunter) for my own understanding of chroot and sysctl commands
- [Chroot-distro](https://github.com/Magisk-Modules-Alt-Repo/chroot-distro) for the internet connectivity fix in initial versions
- [Brutal-Busybox](https://github.com/feravolt/Brutal_busybox) for the statically-linked aarch64 BusyBox binary used in various scripts to perform certain operations.
- [docker-systemctl-replacement](https://github.com/gdraheim/docker-systemctl-replacement) for [systemctl](./Docker/scripts/systemctl3.py) implementation in chroot
- [optimizer](https://github.com/OptimizerS1) for the cool banner design :)
- [Maxim-Root](https://github.com/Maxim-Root) for providing me with a server and additional resources for the project
This project is released under the [MIT License](./LICENSE). You are free to use, modify, and distribute it as long as the original copyright notice and license terms are preserved.