Root on Kang's Blog

Custom Redroid Image: From Source Code Build to Feature Enhancement

Wed, 17 Sep 2025 00:00:00 +0000

Overview

Redroid (Remote Android) is a container-based Android runtime environment that can run a complete Android system on Linux servers. This article provides a detailed guide on how to build a fully functional custom Redroid image from AOSP source code, integrating advanced features such as GPS positioning, battery management, and Magisk Root.

Use Cases

Mobile application development and testing
Automated testing environment setup
Android reverse engineering and security research
Cloud-based Android service deployment

Prerequisites

Before starting, please ensure your environment meets the following requirements:

Hardware Requirements

CPU: Recommended 8+ cores, supporting x86_64 architecture
Memory: At least 16GB RAM, 32GB recommended
Storage: At least 100GB available space (SSD recommended)

Software Environment

Operating System: Ubuntu 20.04/22.04 LTS or other modern Linux distributions
Docker: Version 20.10 or higher
Git: Version 2.25 or higher
Python 3: For running build scripts

Network Requirements

Stable network connection (large amount of source code to download)
If encountering network issues, recommend using Tsinghua mirror sources

Step 1: Environment Setup and Source Code Download

1.1 Create Working Directory

1
2
3

# Create dedicated working directory
cd /data
mkdir redroid && cd redroid

Install Google Repo Tool

Repo is a tool developed by Google for managing multiple Git repositories, essential for AOSP projects.

# Download and install repo tool
curl -k https://storage.googleapis.com/git-repo-downloads/repo > /usr/local/bin/repo
chmod a+x /usr/local/bin/repo

# Configure Git user information (required)
git config --global user.email "your-email@example.com"
git config --global user.name "YourName"

Note: Please replace the email and username with your actual information.

Initialize AOSP Source Repository

# Initialize repo using Tsinghua mirror for accelerated download
repo init -u https://mirrors.tuna.tsinghua.edu.cn/git/AOSP/platform/manifest \
    --git-lfs --depth=1 -b android-15.0.0_r36

# Add Redroid-specific local manifest configuration
git clone https://git.coderkang.top/Android/local_manifests.git \
    .repo/local_manifests -b 15.0.0

Sync Source Code

1
2

# Start syncing source code (time-consuming, please be patient)
repo sync -c

Tip: Initial sync may take 2-4 hours, depending on network conditions. Recommend using screen or tmux to run in background.

Step 2: Magisk Module Integration

Magisk is a popular Android Root solution that provides system-level permission management.

Extract Magisk Components

1
2
3

# Enter Magisk directory and execute extraction script
cd /data/redroid/vendor/magisk
python3 magisk.py

This script will automatically download the latest version of Magisk APK and extract necessary binary files and modules, integrating them into the system image.

Step 3: Apply Custom Patches

Download and Apply Redroid Patches

# Return to main directory
cd /data

# Get Redroid-specific patch set
git clone https://git.coderkang.top/Android/redroid-patches.git

# Apply all patches to source code
./redroid-patches/apply-patch.sh /data/redroid

These patches include:

GPS Functionality: Enable location service support
Battery Management: Simulate battery status and power management
Network Enhancement: Improve network connection stability
Performance Optimization: Performance tuning for container environments

Step 4: Docker Build Environment Setup

Create Build Container

# Get build tools
git clone https://git.coderkang.top/Android/redroid-doc.git
cd redroid-doc/android-builder-docker

# Build Docker image (contains all build dependencies)
docker build \
    --build-arg userid=$(id -u) \
    --build-arg groupid=$(id -g) \
    --build-arg username=$(id -un) \
    -t redroid-builder .

Start Build Environment

# Start build container, mount source code directory
docker run -it --rm \
    --hostname redroid-builder \
    --name redroid-builder \
    -v /data/redroid:/src \
    redroid-builder

Step 5: Compile Android System

Configure Build Environment

# Execute the following commands inside the container
cd /src

# Initialize build environment
. build/envsetup.sh

# Select build target (ARM64 architecture, user debug version)
lunch redroid_arm64_only-ap3a-userdebug

Start Compilation

1
2

# Start compilation process (time-consuming, recommend using -j parameter to specify parallelism)
m -j$(nproc)

Compilation Time: Depending on hardware configuration, compilation usually takes 1-3 hours.

Step 6: Image Packaging and Deployment

Create Docker Image

After compilation is complete, the generated system files need to be packaged into a Docker image.

# Exit build container, return to host machine
exit

# Enter compilation output directory
cd /data/redroid/out/target/product/redroid_arm64_only

# Mount system images (read-only)
sudo mount system.img system -o ro
sudo mount vendor.img vendor -o ro

# Package as Docker image
sudo tar --xattrs -c vendor -C system --exclude="./vendor" . | \
    docker import -c 'ENTRYPOINT ["/init", "androidboot.hardware=redroid", "ro.setupwizard.mode=DISABLED"]' \
    - redroid:custom

# Unmount image files
sudo umount system vendor

Verify Image

# View created image
docker images | grep redroid

# Test starting container
docker run -itd --rm --memory-swappiness=0 \
    --name redroid-test \
    -p 5555:5555 \
    redroid:custom

Function Verification and Usage

Verify Root Permissions

# Connect to Redroid container
adb connect localhost:5555

# Verify Root permissions
adb shell su -c "id"

Verify GPS Functionality

1
2

# Check GPS service status
adb shell dumpsys location

Verify Battery Management

1
2

# View battery status
adb shell dumpsys battery

Common Issues and Solutions

Compilation Errors

Issue: Insufficient memory causing compilation failure

1
2

# Solution: Reduce parallelism
m -j4  # Use fewer parallel tasks

Issue: Insufficient disk space

1
2

# Solution: Clean compilation cache
make clean

Runtime Issues

Issue: Container cannot start

# Check kernel modules
lsmod | grep binder
lsmod | grep ashmem

# If missing, load modules
sudo modprobe binder_linux
sudo modprobe ashmem_linux

Issue: ADB connection failure

1
2
3

# Restart ADB service
adb kill-server
adb start-server

Optimization Recommendations

Performance Optimization

Memory Configuration: Allocate sufficient memory to containers (recommended 4GB+)
CPU Configuration: Enable CPU hotplug support
Storage Optimization: Use SSD storage to improve I/O performance

Security Considerations

Network Isolation: Use custom Docker networks
Permission Control: Limit container permissions, avoid privileged mode
Data Persistence: Properly configure data volume mounts

Summary

Through the detailed guidance in this article, you have successfully built a fully functional custom Redroid image. This image integrates advanced features such as GPS, battery management, and Magisk Root, meeting various development and testing needs.

In practical use, you can further customize system configurations, add more functional modules, or optimize performance parameters according to specific requirements. Redroid’s flexibility makes it an ideal choice for Android development and testing.

Next Steps

Explore more Magisk module integrations
Configure Continuous Integration/Continuous Deployment (CI/CD)
Set up multi-instance cluster environments
Integrate automated testing frameworks

Using AutoJS on Redroid: Build, Troubleshooting, and Automation

Tue, 02 Sep 2025 00:00:00 +0000

Introduction

In a previous post, I explained how to configure Redroid in Docker and obtain root access with Magisk. As some open-source modules raised their minimum Magisk version requirements, this article adopts ayasa520/redroid-script to rebuild the image and update the root approach. It also introduces AutoJS to handle autostart and automation-click scenarios, documenting the complete flow from building and composing to troubleshooting.

Compliance & Risk Notice
This article is for learning and research only. Operations involving certificates, root, system modules, and network redirection may pose compliance and security risks. Ensure you have proper authorization for any production use or actions involving third-party systems. Device identifiers in the article (e.g., IMEI) are examples—replace them with your own compliant, fictitious values.

Environment & Prerequisites

Docker / Docker Compose
A Linux host capable of running Redroid
ADB / Scrcpy (for debugging and screen casting)
Base apps: MT Manager, Termux, AutoJsPro, JustTrustMe
Magisk modules: LSPosed, AlwaysTrustUserCerts, Systemless Hosts
Unified resource pack (download link at the end)

Build a Redroid Image with Magisk Included

Fetch the script and install dependencies

git clone https://github.com/ayasa520/redroid-script
cd redroid-script

apt update && apt install -y lzip
pip install -r requirements.txt

Extend Android version choices (example: 14/15)

If you need Android 14/15, add the options in redroid.py:

def main():
    ...
    parser.add_argument('-a', '--android-version',
                        dest='android',
                        help='Specify the Android version to build',
                        default='11.0.0',
-                        choices=['13.0.0', '12.0.0', '12.0.0_64only', '11.0.0', '10.0.0', '9.0.0', '8.1.0'])
+                        choices=['15.0.0_64only', '15.0.0', '14.0.0_64only', '14.0.0',
+                                 '13.0.0_64only', '13.0.0', '12.0.0', '12.0.0_64only',
+                                 '11.0.0', '10.0.0', '9.0.0', '8.1.0'])

Build the image with Magisk

1
2

python3 redroid.py -a 15.0.0_64only -m
# New image: redroid/redroid:15.0.0_64only_magisk

Launch Redroid

Example docker-compose.yaml:

name: android
services:
  redroid_15_1:
    image: redroid/redroid:15.0.0_64only_magisk
    container_name: redroid_15_1
    restart: unless-stopped
    privileged: true
    networks:
      android:
        ipv4_address: 172.18.0.252
    ports:
      - "45555:5555"
    volumes:
      - ./redroid_15_1:/data
    command:
      - androidboot.hardware=mt6891
      - androidboot.hwc=CN
      - androidboot.redroid_height=2400
      - androidboot.redroid_width=1080
      - ro.boot.hwc=CN
      - ro.product.manufacturer=Xiaomi
      - ro.product.brand=Xiaomi
      - ro.product.model=2211133C
      - ro.product.marketname=Xiaomi 13
      - ro.product.device=fuxi
      - ro.product.name=fuxi
      - ro.build.product=fuxi
      - ro.product.mod_device=fuxi
      - ro.secure=0
      - ro.product.locale=zh-CN
      - ro.product.locale.language=zh
      - ro.product.locale.region=CN
      - persist.sys.locale=zh-CN
      - persist.sys.locale_list=zh-CN,en-US
      - persist.sys.timezone=Asia/Shanghai
      - persist.sys.time_12_24=24

networks:
  android:
    driver: bridge
    ipam:
      config:
        - subnet: 172.18.0.0/16

Startup & connection:

docker compose up -d
docker compose ps
docker compose logs -f redroid_15_1

adb connect 127.0.0.1:45555
adb devices
adb shell whoami

Once running properly, the ADB service is exposed on port 45555.

Install Base Apps & Modules

Apps (from the unified pack at the end)

MT Manager
Termux
AutoJsPro
JustTrustMe

Magisk modules

LSPosed
AlwaysTrustUserCerts
Systemless Hosts

Recommended order: install the user certificate first (see below), then enable AlwaysTrustUserCerts, and enable/adjust other modules as needed to improve Zygisk activation stability.

Root Authorization & the `su` Path

Symptoms

Running su in Termux correctly triggers the Magisk grant dialog.
MT Manager and Shizuku fail to obtain root.
logcat shows no obvious errors.

Resolution

Explicitly set the su path to /sbin/su.
Reference issue: https://github.com/ayasa520/redroid-script/issues/47#issuecomment-3242690759.

Notes Different apps discover and invoke root differently. An explicit path avoids visibility issues caused by environment variables or mount strategies. If you customized PATH, SELinux, or overlayfs, evaluate their impact accordingly.

Troubleshooting Zygisk Not Activating

Symptom Magisk’s Zygisk keeps saying “restart required,” but remains inactive after reboot. Logs are sparse.

Reusable steps

Install the user certificate in system settings first.
Enable AlwaysTrustUserCerts via LSPosed/module manager.
Reboot Redroid so Zygisk and related modules can initialize and mount properly.

If it still fails, try clearing module caches, check LSPosed version compatibility, and if necessary roll back to a stable Magisk/Redroid combination.

Deploy AutoJS for Automation

Use cases Execute automated clicks, heartbeats, or form-filling after specific apps launch.

Compliance Reminder The following is for your own environment and authorized testing only. Do not apply it to apps or services without explicit permission.

Prepare the AutoJS service

# Extract autojserver.tar.gz from the resource pack to your compose directory
tar -zxvf autojserver.tar.gz

cd autojserver
chmod +x main.sh
bash main.sh
# Initialization generates a self-signed certificate and other runtime files

Compose setup

name: android
services:
  redroid_15_1:
    image: redroid/redroid:15.0.0_64only_magisk
    container_name: redroid_15_1
    restart: unless-stopped
    privileged: true
    networks:
      android:
        ipv4_address: 172.18.0.252
    ports:
      - "45555:5555"
    volumes:
      - ./redroid_15_1:/data
    command:
      - androidboot.hardware=mt6891
      - androidboot.hwc=CN
      - androidboot.redroid_height=2400
      - androidboot.redroid_width=1080
      - ro.boot.hwc=CN
      - ro.product.manufacturer=Xiaomi
      - ro.product.brand=Xiaomi
      - ro.product.model=2211133C
      - ro.product.marketname=Xiaomi 13
      - ro.product.device=fuxi
      - ro.product.name=fuxi
      - ro.build.product=fuxi
      - ro.product.mod_device=fuxi
      - ro.secure=0
      - ro.product.locale=zh-CN
      - ro.product.locale.language=zh
      - ro.product.locale.region=CN
      - persist.sys.locale=zh-CN
      - persist.sys.locale_list=zh-CN,en-US
      - persist.sys.timezone=Asia/Shanghai
      - persist.sys.time_12_24=24

  autojserver:
    image: autojserver:latest
    build:
      context: ./autojserver
      dockerfile: Dockerfile
    container_name: autojserver
    restart: unless-stopped
    working_dir: /data
    networks:
      android:
        ipv4_address: 172.18.0.251
    command: ["python", "/data/main.py"]
    volumes:
      - ./autojserver:/data

networks:
  android:
    driver: bridge
    ipam:
      config:
        - subnet: 172.18.0.0/16

Start and view logs

1
2
3

docker compose up -d
docker compose ps
docker compose logs -f autojserver

Inject certificates and hosts

# User certificate: for manual installation in system settings
cp ./autojserver/ca.crt ./redroid_15_1/media/0/Download/

# Systemless Hosts: ensure the module is installed
cp -rf ./autojserver/hosts ./redroid_15_1/adb/modules/hosts/system/etc/

Then, in Settings → Security → Encryption & credentials (or Certificate management) → Install from storage, install the ca.crt user certificate. In JustTrustMe, check AutoJS / target apps in the scope. Reboot Redroid.

Resource Download

Unified resource pack

Apps: MT Manager, Termux, AutoJsPro, JustTrustMe
Modules: LSPosed, AlwaysTrustUserCerts, Systemless Hosts