A guide on how to use Lindroid

Guide-of-Lindroid.md

An Unofficial Guide of Lindroid

Official Guide: https://t.me/linux_on_droid/1263

What is Lindroid?

Lindroid is an Android app that lets you run Linux in a container, with support for hardware-acceleration. Official group: https://t.me/linux_on_droid

How to Compile Lindroid?

1. Ensure your device has the necessary configurations:

   • Obtain a usable device configuration, kernel source, and ROM source code for your device.

2. Clone the necessary repositories Linux-on-droid repository:

   • Clone vendor_lindroid from to $ANDROID_BUILD_TOP/vendor/lindroid.

     git clone https://github.com/Linux-on-droid/vendor_lindroid vendor/lindroid
     

   • Clone external_lxc to $ANDROID_BUILD_TOP/external/lxc.

     git clone https://github.com/Linux-on-droid/external_lxc external/lxc
     

   • Clone libhybris to $ANDROID_BUILD_TOP/libhybris.

     git clone https://github.com/Linux-on-droid/libhybris libhybris
     

   • Pick the patch from https://gerrit.libremobileos.com/c/LMODroid/platform_frameworks_native/+/12936 to $ANDROID_BUILD_TOP/frameworks/native.

     cd $ANDROID_BUILD_TOP/frameworks/native
     wget https://github.com/LMODroid/platform_frameworks_native/commit/51b680f33b66e06b18725fdf9a54fa923c14a10b.patch
     git am 51b680f*.patch
     cd $ANDROID_BUILD_TOP
     

     If Android 13, use https://review.lineageos.org/c/LineageOS/android_frameworks_native/+/351543

     cd $ANDROID_BUILD_TOP/frameworks/native
     wget https://github.com/LineageOS/android_frameworks_native/commit/94dd1b1bda79e783b1610470a5284bb6f300340e.patch
     git am 94dd1b1*.patch
     cd $ANDROID_BUILD_TOP
     

3. Modify device configurations:

   • Add $(call inherit-product, vendor/lindroid/lindroid.mk) to your device's mk file.
   • Add BOARD_KERNEL_CMDLINE += androidboot.selinux=permissive or BOARD_BOOTCONFIG += androidboot.selinux=permissive for GKI devices to BoardConfig.mk.
   • Ensure SELinux is set to permissive mode for Lindroid.

4. Kernel configuration:

   • For non-GKI devices, refer to kernel configurations for enabling LXC/Docker support.

     Search keywords 'lxc docker android' in GitHub

   • Example kernel configurations provided by Lindroid developers include:

     CONFIG_SYSVIPC=y
     CONFIG_UTS_NS=y
     CONFIG_PID_NS=y
     CONFIG_IPC_NS=y
     CONFIG_USER_NS=y
     CONFIG_NET_NS=y
     CONFIG_CGROUP_DEVICE=y
     CONFIG_CGROUP_FREEZER=y
     

   • For GKI 5.10, refer to this source. For 5.15 and 6.1, explore the configurations accordingly.
   • I recommend that compile KernelSU simultaneously for root access (use v0.9.5 tag for non-GKI). Or use magisk etc.

5. Build your ROM using the userdebug variant:

   • Avoid using user variant for now.
   • If FCM (Framework Compatibility Matrix) errors occur, leading to OTA package build failure, manually modify configurations in the $ANDROID_BUILD_TOP/kernel/configs/[ANDROID VERSION]/[KERNEL VERSION]/ directory of the ROM source.

How to Use Lindroid?

1. Download and prepare the root filesystem

   • Download the pre-packaged Debian image from lindroid-rootfs releases or Lindroid website. Ensure that the folders (e.g., etc/, bin/, usr/...) in the archive are at the root level, not within an inner directory like rootfs/. If not, repack it.
   • Push it to /data/data/org.lindroid.ui/files/rootfs.tar.gz (rename to rootfs).
   • Open Lindroid and follow the prompts to create the container.

2. Configure your device

   • Ensure network connection, disable auto-rotate, set screen timeout to 30 minutes, and grant root access to shell in developer options.
   • Use adb shell or terminal to enter:

     su
     lxc_ls
     lxc_attach default
     /bin/bash -c "source /etc/profile && exec su - root"

   • Optionally, change Debian source mirrors for CN users:

     sed -i 's/deb.debian.org/mirrors.bfsu.edu.cn/g' /etc/apt/sources.list

   • Then upgrade all packages (Especially Kwin etc. from lindroid)

     apt update && apt-get -o Dpkg::Options::="--force-overwrite" full-upgrade

   • If there is a network error, try setting DNS server:

     echo "nameserver 8.8.8.8" > /etc/resolv.conf

3. Test and configure the graphical interface:

   • Test graphics with test_hwcomposer.
   • Start or restart SDDM service:

     systemctl restart sddm

   • If touch doesn't work, try:

     sudo setcap cap_dac_read_search+ep /usr/bin/startplasma-wayland
     sudo setcap cap_dac_read_search+ep /usr/bin/kwin_wayland
     sudo setcap cap_dac_read_search+ep /usr/bin/sddm

   • Use evtest to check for Lindroid virtual input devices. Adjust /dev/uinput permissions if needed and restart Lindroid in adb shell.

     su -c chmod 777 /dev/uinput
     am force-stop org.lindroid.ui

Some supplements:

• The most important thing is patience and waiting. SDDM usually starts one or two minutes after starting Lindroid. Please do not do anything during this period of black screen.
• XDG hack to run kwin manually:

  export XDG_RUNTIME_DIR=/tmp/runtime-lindroid
  mkdir -p $XDG_RUNTIME_DIR
  chmod 700 $XDG_RUNTIME_DIR
  

• Execute this command to get input:

  groupadd --gid 1004 android_input
  usermod -aG android_input lindroid
  usermod -aG android_input sddm
  

  Modify /etc/logind.conf to fix power button
  Restart systemd-logind on every login to run sddm
• Try:

  loginctl kill-user lindroid
  systemctl restart systemd-logind
  

  as root if sddm doesn't work
• Download this public-key.asc and push to /etc/apt/trusted.gpg.d/lindroid.asc to resolve the GPG warning of apt update
• Install kscreen to restore display settings, kinfocenter to restore about system option.

Notes:

• Default username and password are both lindroid.
• Subsequent usage may encounter touch issues; restart Lindroid, sddm and systemd-logind as needed.
• External keyboard/mouse is recommended. KDE Connect can help with remote control.
• There are also apps that can turn your other phone into a keyboard via Bluetooth.
• Strongly suggest SSH for better terminal experience.

This guide is a compilation of my personal exploration and guidance from Lindroid developers [Erfan Abdi, Luka, Nick].

Expect some initial issues, but it’s a promising start. Explore further on your own.

If you need more support, please join the official Lindroid group. Read the official #guide to get started

28/6/24

A tested Ponce's AOSP-14 TrebleDroid/PHH GSI with Lindroid support:
https://1drv.ms/f/c/ff4d884b3727a25f/El-iJzdLiE0ggP9qGgAAAAABhniQ8u6RdFucpUhTobrcHg?e=O0H6pw

Ensure your kernel is supported and selinux is set to permissive in the boot cmdline.

You can flash the system.img or directly load the ZIP using DSU Sideloader.

You should run "perspectived" manually as root before running Lindroid because of sepolicy issue.

Have a try and good luck:)))

---

2025.6.9 Add LineageOS 22.2 GSI with lindroid. Build with https://github.com/AndyCGYan/lineage_build_unified + https://github.com/Linux-on-LineageOS

For lineage-21.0 branch (Android 14), it needs https://review.lineageos.org/c/LineageOS/android_frameworks_native/+/409935

it would be great if there is a video tutorial, PLEASE

For those who also want to build Lindroid on LineageOS, I created an organization for doing so at ease.
The instructions to build ROM can refer to page like https://wiki.lineageos.org/devices/rtwo/build/variant2/. However, instead of running

repo init -u https://github.com/LineageOS/android.git -b lineage-22.2 --git-lfs --no-clone-bundle

You should use the android repo from Linux-on-LineageOS instead,

repo init -u https://github.com/Linux-on-LineageOS/android.git -b lineage-22.2 --git-lfs --no-clone-bundle

Beside this, you can also use the linux-on-lineage-cicd docker image to build one automatically. Basically, it is a fork from docker-lineage-cicd. The example commands can be found at https://github.com/lineageos4microg/docker-lineage-cicd/wiki#examples.
For example:

docker run \
    -e "BRANCH_NAME=lineage-22.2" \
    -e "DEVICE_LIST=rtwo" \
    -e "WITH_GMS=false" \
    -v "/home/user/lineage:/srv/src" \
    -v "/home/user/zips:/srv/zips" \
    -v "/home/user/logs:/srv/logs" \
    -v "/home/user/cache:/srv/ccache" \
   linuxonlineageos/linux-on-lineage-cicd

Only Motorola X40 (rtwo) was tested. For other devices, they may not work as intended. You can fork the device related repository and fix the errors. PRs are welcome. :)