Android AI Stack

English · 简体中文

A local-first AI toolchain for an Android phone running Termux and a Kali PRoot. OpenCode, Claude Code, Happy's agent, and Happy's server run on the phone. Model inference can use an external API URL/token, just as it does on a desktop.

This repository packages the reusable deployment and validation knowledge. It does not contain provider tokens, personal endpoints, Happy upstream source, or model weights.

Real control surface

This is a token-free UI rendering on a clean AOSP ARM64 emulator. It proves the published app layout and generic Android startup path; it is not evidence for a OnePlus-specific runtime, configured provider credentials, or DSP power use.

What “local-first” means here

Happy app -> 127.0.0.1 Happy server -> local Happy daemon -> local Claude Code
                                                                  |
                                                   Claude/Happy profile -> model API

OpenCode TUI/Web -> independent OpenCode profile -> model API (cloud/relay/local)

• The control plane is self-contained on the phone.
• A remote relay is optional, not required. See happy-relay-deploy if you intentionally need one.
• Local inference is optional. A small llama.cpp server can expose a loopback OpenAI-compatible API for lightweight offline tasks.
• OpenCode and Claude/Happy have separate selectors and active files. Switching either route is explicit and never changes the other client or a service lifecycle.
• The offline Mobile Lab Control app exposes five independent native widgets: Happy, llama.cpp, Claude/Happy models, OpenCode Web, and OpenCode models. Termux:Widget remains an opt-in terminal fallback.

Repository layout

• skills/deploy-android-ai-stack/ — install and operate the runtime.
• skills/validate-android-ai-stack/ — bounded, evidence-based acceptance checks.
• apps/mobile-lab-control/ — dependency-free Android AppWidget source and reproducible build script.
• config/profiles/ — safe provider-profile templates.
• docs/ — architecture and the verified OnePlus 8T case.
• manifests/ — facts captured from tested devices, with secret-free values.
• THIRD_PARTY_NOTICES.md — provenance for the minimal Happy loopback patch.

Quick start

1. Copy this repository or the two skill directories to the machine that controls the Android device.
2. Ask Codex to use $deploy-android-ai-stack, or follow its SKILL.md.
3. Create a provider profile from one of config/profiles/*.example and put the token in the referenced private file.
4. Install the native control bridge and a checksum-verified APK from GitHub Releases.
5. Use $validate-android-ai-stack to run zero-call checks first, then opt in to at most one model call per client.

For an on-phone checklist, use the bilingual phone quick start.

The scripts refuse unsafe secret permissions and use loopback bindings by default. They do not automatically download a model or expose a service to the LAN.

Verified baseline

The initial case is a OnePlus 8T KB2000 on Android 14 / LineageOS 21 with about 12 GB RAM. The device-local architecture and an optional Qwen3 0.6B llama.cpp fallback have both been exercised. Exact versions and evidence are recorded in the case study and case manifest.

Capability	Initial case	Public automation
OpenCode TUI/Web	exercised end to end	bounded checker included
Claude Code CLI	exercised end to end	one-call checker included
Phone-local Happy	exercised end to end	lifecycle wrapper included
Provider switching	exercised on the private device config	redacted generic profiles included
llama.cpp local model	Qwen3 0.6B Q8, API and local-lite passed	authenticated loopback lifecycle and bounded checker included
Native control widgets	five controls exercised on Android 14; lifecycle and model routes stayed independent	source, allow-list bridge, bilingual UI, and release APK included

The 2026-08-09 phone acceptance also exercised real inference: OpenCode and Claude CLI each returned an exact nonce through the OpenAI-labelled relay, and Happy returned an exact nonce from the mobile UI. The Android 14 widget path was fixed to use a user-initiated activity, and both local services stopped cleanly afterward.

“Included” does not mean automatically installed. Upstream binaries and model weights remain explicit, pinned operator choices.

Ecosystem

This is one module in the oneplus-8t-mobile-lab:

• pocket-pentest owns the Android/Termux/Kali foundation.
• android-device-test owns reusable device evidence collection.
• happy-relay-deploy owns the optional remote Happy relay.

Security

Read SECURITY.md before adding a profile or exposing a web UI. Provider secrets and real endpoints must never be committed.

License

MIT. Upstream tools retain their own licenses and trademarks.