opencecs/tebox

Project Overview

tebox is an Android GSI runtime base built on QEMU. It boots generic ARM64 GSI images and bundles two graphics acceleration paths, gfxstream (ANGLE + Vulkan) and VirGL (Mesa), plus a self-developed ARM Mali GPU passthrough technology. The goal is to give developers a repeatable environment for validating a GSI, extending the runtime, and running automated tests.

The project is aimed at Android platform and graphics developers who need to boot and inspect GSI builds outside a physical device. It is explicitly not a one-click flash package for a specific phone; whether a given GSI boots depends on its Treble/VINTF requirements, and vendor proprietary partitions and closed-source services must be adapted by the user.

Supported Hosts

Host	Notes
macOS ARM64 (Apple Silicon M1–M4)	Recommended; HVF with gfxstream / VirGL verified
Linux ARM64	Native build and run with KVM
Linux x86_64	Mainly for cross-compiling Android ARM64 guests
Windows x86_64	Native QEMU/VirGL PE runtime

Quick Start

Git LFS is required because the image assets are stored through it. Install it first (macOS: brew install git-lfs; Ubuntu/Debian: sudo apt-get install git-lfs), then clone and pull the assets:

git lfs install
git clone https://github.com/opencecs/tebox.git
cd tebox
git lfs pull

After that, build and run the AOSP sample variant:

bash .ci/install-deps.sh
source build/envsetup.sh
lunch aosp_arm64-BP4A.251205.006
m
SNAPSHOT=1 ./run aosp_arm64-BP4A.251205.006

GSI variant trees live on corresponding GSI/... branches (the AOSP example is on GSI/AOSP/aosp_arm64-BP4A.251205.006). To try another GSI, check out its branch and replace src/aosp/<variant>/images/system.img. Community GSI images are linked from Mystic GSI Updates.

Usage Constraints

The build flow assumes a Unix-like shell with AOSP build tooling (build/envsetup.sh, lunch, m); the README does not document a separate Windows-native build procedure. Boot success is not guaranteed for every GSI, since Treble and VINTF compatibility of the target image matters. Extracting firmware or vendor images from devices requires users to comply with local law, vendor license agreements, and copyright.

The project is licensed under Apache-2.0; bundled third-party source and binaries keep their own licenses.

AI-Assisted Development

Agents and automation tooling are directed to read the root README and then .ai/README.md for skills, prompts, and development workflow, with engineering constraints in .ai/AGENTS.md.

HotRepo's take

There are no HotRepo ranking records or snapshots for this repository, so its position on the daily chart is unknown. The repository is young (created 2026-09-29) but has accumulated 92 stars and 60 forks with C as the primary language, which is a meaningful fork-to-star ratio for a project that depends on Git LFS and an AOSP build pipeline. The README is concrete about host support, build commands and GSI branch layout, which makes the project reviewable from the documentation itself; the main open question for adopters is how much of the Mali GPU passthrough and the per-variant trees is actually present in the repository, since the README points to separate GSI/... branches and does not inventory them.