Deploying Custom AOSP to Anbox: A Comprehensive Guide to Flashing and Testing Your Android Build

Introduction

Anbox (Android in a Box) provides a way to run Android applications on GNU/Linux distributions by putting the Android operating system into a container, abstracting hardware access, and integrating system services into a standard Linux environment. While Anbox typically ships with a pre-built Android image, developers and enthusiasts often need to test their custom Android Open Source Project (AOSP) builds. This guide provides a detailed, expert-level walkthrough on how to compile a custom AOSP image specifically for Anbox and deploy it, allowing you to thoroughly test your modifications and custom features within a controlled Linux environment.

What is Anbox?

Anbox leverages Linux kernel features like namespaces and cgroups to run a full Android system in a container, essentially bridging Android’s Binder IPC with standard Linux mechanisms. This approach offers a lightweight and integrated solution compared to traditional virtual machine-based emulators, making it ideal for development and testing if you require closer interaction with the host system.

Why Custom AOSP?

Building custom AOSP images is crucial for several use cases:

Custom ROM Development: Testing new features, optimizations, or security patches before deploying to physical devices.
Embedded Systems: Prototyping and validating Android builds for specialized hardware.
Security Research: Analyzing Android internals or specific security vulnerabilities within a sandboxed environment.
Feature Prototyping: Experimenting with new Android features or API changes without the overhead of hardware flashing.

Prerequisites

Before you begin, ensure you have the following:

A Linux machine (Ubuntu 20.04 LTS or newer is recommended) with at least 200GB free disk space and 16GB RAM for the AOSP build process.
Anbox installed and functional on your Linux machine.
Basic familiarity with Linux command-line operations.
Git and other essential build tools installed (covered in the setup section).

Setting Up Your AOSP Build Environment

Downloading AOSP Source

First, set up your environment for AOSP building. You’ll need `repo` for source synchronization and various build dependencies.

sudo apt update && sudo apt upgrade -y
sudo apt install -y git-core gnupg flex bison build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libsdl1.2-dev libxml2 libxml2-utils xsltproc libssl-dev librepo-dev
mkdir -p ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
export PATH=~/bin:$PATH

Now, initialize the AOSP repository. For Anbox compatibility, it’s often best to use an older, stable branch like Android 7.1.2 (Nougat) or Android 9.0 (Pie), as Anbox’s kernel and container setup might not fully support the latest AOSP versions without significant modifications. Let’s use Android 7.1.2 as an example, as it’s well-supported by many Anbox installations.

mkdir aosp-anbox
cd aosp-anbox
repo init -u https://android.googlesource.com/platform/manifest -b android-7.1.2_r39
repo sync -j$(nproc)

This synchronization process can take several hours depending on your internet connection.

Building AOSP for Anbox

Choosing the Right Target

Anbox runs a standard Android system. For building, you’ll typically target `aosp_x86` or `aosp_x86_64` depending on your host system architecture and desired Android version. Anbox itself uses `x86_64` for its default images. For this guide, we’ll focus on `x86_64` to match typical Anbox deployments.

First, set up the build environment:

source build/envsetup.sh

Then, select your build target:

lunch aosp_x86_64-userdebug

`userdebug` is preferred for development as it includes debugging capabilities while being closer to a production build than `eng`.

Initiating the Build

Now, start the actual build process. This will compile the entire AOSP source code into a runnable Android image.

make -j$(nproc)

This command can take several hours, even on powerful machines. The `-j$(nproc)` flag tells `make` to use all available CPU cores for compilation, speeding up the process. Upon successful completion, you will find your compiled images in the `out/target/product/generic_x86_64` directory.

Packaging Your Custom Anbox Image

Anbox requires a specific image format, often a squashfs image containing `system.img`, `vendor.img`, `ramdisk.img`, etc. For a custom build, the most critical component is `system.img`. The default Anbox installation uses a single `android.img` (often a squashfs) which encapsulates these. We will replace the primary `system.img` within Anbox’s existing structure or create a new squashfs if necessary.

Extracting Necessary Files

Navigate to your build output directory:

cd out/target/product/generic_x86_64

Here you will find `system.img`. This is the core image we want to use. Anbox also uses a `ramdisk.img` and a `kernel`. The kernel is usually provided by Anbox itself, but if you built a custom kernel alongside AOSP (which is a more advanced topic), you’d also package that.

Creating the Anbox-Compatible Image (Optional, if replacing the entire `android.img`)

If you wanted to create a standalone `android.img` that Anbox could directly load, you would typically use `mksquashfs`. However, a simpler approach for custom AOSP flashing is to replace the `system.img` within the existing Anbox structure, as Anbox handles the `boot.img` (containing kernel and ramdisk) separately or uses its own kernel module.

Deploying the Custom AOSP Image to Anbox

Now, let’s deploy your newly built `system.img` to Anbox.

Stopping Anbox and Backing Up

First, ensure Anbox is stopped and back up the existing Android image.

sudo systemctl stop anbox-container-manager.service
sudo systemctl stop anbox.service

# Find the location of Anbox images (it's often in /var/lib/anbox)
ANBOX_IMAGE_DIR="/var/lib/anbox"

# Backup the existing image(s)
sudo cp $ANBOX_IMAGE_DIR/android.img $ANBOX_IMAGE_DIR/android.img.bak

# If Anbox uses separate system.img, ramdisk.img, etc.
sudo cp $ANBOX_IMAGE_DIR/system.img $ANBOX_IMAGE_DIR/system.img.bak
sudo cp $ANBOX_IMAGE_DIR/ramdisk.img $ANBOX_IMAGE_DIR/ramdisk.img.bak

Note: Anbox’s image structure can vary. Some installations use a single `android.img` (which is a squashfs containing `system.img`, `ramdisk.img`, etc.), while others might expose `system.img` directly. You may need to inspect `$ANBOX_IMAGE_DIR`.

Replacing the System Image

If your Anbox installation uses a direct `system.img` at `/var/lib/anbox`, you can directly replace it:

# Replace with your AOSP build output directory
MY_AOSP_BUILD_DIR="/home/user/aosp-anbox/out/target/product/generic_x86_64"
sudo cp $MY_AOSP_BUILD_DIR/system.img $ANBOX_IMAGE_DIR/system.img

# Also copy ramdisk.img if Anbox uses it separately
sudo cp $MY_AOSP_BUILD_DIR/ramdisk.img $ANBOX_IMAGE_DIR/ramdisk.img

Advanced: Replacing within `android.img` (SquashFS)
If your Anbox uses a single `android.img` (squashfs), you’ll need to unsquash it, replace `system.img` inside, and then re-squash it. This is more complex:

# Install squashfs-tools if not already installed
sudo apt install squashfs-tools

# Unpack the existing Anbox image
sudo unsquashfs $ANBOX_IMAGE_DIR/android.img

# The contents will be in 'squashfs-root'
cd squashfs-root

# Replace system.img
sudo rm system.img
sudo cp $MY_AOSP_BUILD_DIR/system.img system.img

# Re-squash the image (might need to do this outside squashfs-root)
cd ..
sudo mksquashfs squashfs-root $ANBOX_IMAGE_DIR/android_custom.img -comp xz -b 256k -noappend

# Backup original and replace
sudo mv $ANBOX_IMAGE_DIR/android.img $ANBOX_IMAGE_DIR/android.img.original
sudo mv $ANBOX_IMAGE_DIR/android_custom.img $ANBOX_IMAGE_DIR/android.img

# Clean up
sudo rm -rf squashfs-root

Restarting Anbox and Verification

After replacing the image, restart Anbox services:

sudo systemctl start anbox-container-manager.service
sudo systemctl start anbox.service

Now, launch the Anbox Applications window from your desktop environment’s applications menu. You should see your custom AOSP build booting up. The first boot might take longer than usual.

Testing Your Custom AOSP Build

Once Anbox boots with your custom image, perform the following tests:

Basic Functionality: Navigate through the UI, open Settings, and check for stability.
Pre-installed Apps: Verify if default apps like Calculator, Clock, etc., are present and functional.
ADB Connection: Connect to Anbox via ADB to install and debug applications. You might need to enable developer options in your custom build.
Networking: Ensure the Android system can access the internet.
Custom Modifications: If you made specific changes to AOSP, verify those changes are reflected and working as expected.

Troubleshooting Common Issues

Anbox Not Starting: Check `sudo journalctl -u anbox-container-manager.service` and `sudo journalctl -u anbox.service` for errors.
Boot Loops: An incorrect `system.img` or incompatible kernel/ramdisk can cause boot loops. Double-check your build target and Anbox’s expected image structure. Revert to the `android.img.bak` if necessary.
Android Mobile Specs & Compare Directory

Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!
Compare Devices Specs →