Mobilecode

Your phone is a development machine. Install one APK, add your own API key, and let AI write code, run commands, and manage projects right on your Android device — no PC, no server, no cloud setup.

English | 中文文档

---

Table of Contents

• What is Mobilecode?
• Features
• Quick Start
• Supported Model Providers
• Build from Source
• Architecture
• How It Works
• Project Structure
• Requirements
• Troubleshooting
• Roadmap & Docs
• Security & License

---

What is Mobilecode?

Mobilecode is an AI coding workspace for Android. It embeds a complete Linux userland (Termux-style bootstrap) — Node.js 24, npm, the Codex CLI, and its native ARM64 engine, plus a self-hosted web workspace — directly inside the APK.

On first launch, the environment is extracted fully offline (4-thread parallel extraction, ~1 minute). No apt install, no npm install, no root, no server. The only network your device needs is the one API call to your chosen model provider.

┌─────────────┐   install APK   ┌──────────────────────────────────────────┐
│   APK       │ ──────────────► │  Terminal / Web workspace (localhost)    │
│  images0-3  │                 │  Codex CLI + native engine               │
│  (built-in) │   extract once  │  Node.js 24 + npm                        │
│             │ ──────────────► │  Termux Linux userland                   │
└─────────────┘                 └──────────────────────────────────────────┘
                                     │  HTTPS (API calls only)
                                     ▼
                              OpenAI · OpenRouter · DeepSeek · Qwen · GLM · …

Features

• Zero-setup AI coding on mobile — prebuilt, versioned runtime image inside the APK
• Fully offline first-run install — the environment is extracted, never downloaded
• 4-thread parallel extraction — first launch in about a minute
• Complete model configuration — 8 built-in providers (OpenAI, OpenRouter, DeepSeek, Qwen, Zhipu GLM, Moonshot, Ollama, custom) with preset + free-text model selection, custom OpenAI-compatible Base URL, and per-provider keys
• Secure API key storage — Android Keystore-backed encryption (SecureKeyStore)
• Self-hosted web workspace — served locally on 127.0.0.1:18923, loaded in WebView
• Built-in CONNECT proxy — lets the native binary reach HTTPS endpoints on-device
• Diagnostics & one-tap environment reset — recover without reinstalling
• Battery-optimization aware — runs as a foreground service; survives in background
• English & Chinese UI/error messages — clear, actionable errors with copy-to-clipboard diagnostics

Quick Start

1. Download the APK

   Latest release: release/Mobilecode-v0.7.2-release.apk (~90 MB)

2. Install

   Transfer the APK to your phone and open it. Enable “Install from unknown sources” when prompted.

3. First launch

   The app extracts the built-in runtime environment (progress bar, ~1 minute), then starts the local workspace automatically.

4. Configure a model

   Tap the gear icon (⚙) in the top-right corner → 模型与设置. Pick a provider (OpenAI / OpenRouter / DeepSeek / Qwen / GLM / Moonshot / Ollama / 自定义), choose or type a model, paste your API key, optionally set a custom Base URL (for OpenAI-compatible proxies / self-hosted / local), and tap 保存并重启工作台. You are then ready to chat and code.

Supported Model Providers

Provider	Preset models	Type	Env key
OpenAI	gpt-4.1, gpt-4.1-mini, gpt-4o, o4-mini …	Responses (direct)	OPENAI_API_KEY
OpenRouter	openai/gpt-4.1, anthropic/claude-3.5-sonnet …	Responses (direct)	OPENROUTER_API_KEY
DeepSeek	deepseek-chat, deepseek-reasoner	Chat (via bridge)	DEEPSEEK_API_KEY
Qwen (Alibaba)	qwen-plus, qwen-max, qwen2.5-coder-32b-instruct …	Chat (via bridge)	DASHSCOPE_API_KEY
Zhipu GLM	glm-4.5, glm-4-plus, glm-4-flash …	Chat (via bridge)	ZHIPU_API_KEY
Moonshot (Kimi)	moonshot-v1-8k, moonshot-v1-128k	Chat (via bridge)	MOONSHOT_API_KEY
Ollama (local)	llama3.1, qwen2.5, deepseek-r1 …	Chat (via bridge)	OLLAMA_API_KEY
自定义	任意	Responses 或 Chat（可选）	CUSTOM_API_KEY

Custom Base URL: for OpenAI / OpenRouter / 自定义-Responses, the Base URL is used directly. For Chat-only providers (DeepSeek / Qwen / GLM / Moonshot / Ollama / 自定义-Chat), traffic is routed through the on-device chat-bridge (:18925) that translates the engine's Responses API into Chat Completions. Bring your own API key — it never leaves your device and is stored encrypted in the Android Keystore.

Build from Source

Prerequisites

• JDK 17 (AGP 8.7 / Kotlin 2.1 do not support JDK 21+)
• Android SDK — write sdk.dir=... into android/local.properties (first time: sdkmanager --licenses)
• Python 3.10+
• One-time internet access to build the image: Termux bootstrap / debs / Codex (~150 MB downloads, cached in scripts/.cache; ~80 MB image output)

Steps

cd android

# 1. Assemble the runtime image → app/src/main/assets/images0..3.bin
python3 scripts/build-image.py

# 2. Build the APK
./gradlew :app:assembleDebug
# Output: app/build/outputs/apk/debug/app-debug.apk (~90 MB)

Step 1 is required: the image shards are the app’s runtime. Shipping an APK without them (or with a mismatched .runtime-version) breaks startup.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Android APK (v0.7.2)                      │
│                                                                 │
│  ┌──────────────────────┐        ┌───────────────────────────┐  │
│  │      WebView UI      │        │  MainActivity             │  │
│  │  http://127.0.0.1:   │        │  · setup steps            │  │
│  │       18923          │        │  · diagnostics & reset    │  │
│  └──────────┬───────────┘        └────────────┬──────────────┘  │
│             │                                │                  │
│             ▼                                ▼                  │
│  ┌──────────────────────┐        ┌───────────────────────────┐  │
│  │ codex-web-local      │        │ CodexServerManager        │  │
│  │ workspace server     │◄──────►│ · install/extract (4 thd) │  │
│  │ (Node.js, on-device) │        │ · proxy on 127.0.0.1:18924│  │
│  └──────────┬───────────┘        │ · config/auth (Keystore)  │  │
│             │                    └────────────┬──────────────┘  │
│             ▼                                ▼                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  files/usr  (Termux-style Linux userland, extracted)     │   │
│  │  ├── bin/sh · node · npm · codex                         │   │
│  │  └── lib/node_modules/@openai/codex (+linux-arm64)       │   │
│  │      lib/node_modules/codex-web-local                    │   │
│  └──────────────────────────────────────────────────────────┘   │
│                       │ HTTPS (API calls only)                  │
└───────────────────────┼─────────────────────────────────────────┘
                        ▼
              OpenAI · OpenRouter · DeepSeek · Qwen · GLM · …

Key components:

• build-image.py — assembles a ready-to-run image on the build machine (Termux bootstrap + Node + Codex + workspace), rewrites absolute paths, slims the tree, validates dynamic dependencies, and splits the result into 4 gzip+tar shards for parallel extraction.
• TarExtractor.kt — streams the shards on-device with full GNU/PAX tar support (long names, symlinks, permissions); each shard is extracted by its own thread.
• CodexServerManager.kt — install lifecycle, version checks (needsInstall), CONNECT proxy, workspace server, provider config & health check.
• SecureKeyStore.kt — encrypts your API key with an Android Keystore-backed key.
• MainActivity.kt — step-driven startup flow with progress, error recovery (retry / diagnostics / reset), and the embedded WebView workspace.

How It Works

1. Versioned image — the image carries .runtime-version (currently 0.7.2). If it ever mismatches the app’s expected version, the app re-extracts exactly once, so stale environments can never wedge startup.
2. One-time offline install — first run extracts the shards to files/usr/, writes a full-access Codex config, and initializes a git workspace.
3. Local networking — a Node CONNECT proxy on 127.0.0.1:18924 bridges the native binary to HTTPS; the workspace server listens on 127.0.0.1:18923.
4. Your key, your model — provider + key are written to ~/.codex/config.toml and auth.json inside the app sandbox; only that provider is contacted.

Project Structure

mobilecode-repo/
├── README.md               ← this file
├── README.zh-CN.md         ← 中文版
├── CHANGELOG.md            ← release notes
├── DESIGN.md               ← design notes & decisions
├── SECURITY.md             ← security policy
├── CONTRIBUTING.md         ← how to contribute
├── THIRD_PARTY_NOTICES.md  ← bundled open-source components
├── robots.txt              ← crawler policy (SEO)
├── art/                    ← marketing/hero assets
├── docs/
│   ├── ROADMAP.md          ← roadmap & milestones
│   ├── workbench-audit-2026-09.md ← workbench frontend audit vs 2026 agents
│   └── domestic-models.md  ← domestic model provider notes
├── release/                ← prebuilt APKs
└── android/                ← curated source mirror (full source: openclaw-android)

Requirements

• Android 7.0 (API 24) or newer, ARM64 device
• ~500 MB free storage
• Internet only for model API calls (and, if building, for image downloads)

Troubleshooting

Symptom	Fix
"App not installed" / install fails	① Had a v0.4.x build installed? Uninstall it first — older releases were signed with a different debug certificate, so the system refuses a signature-mismatch upgrade. ② Make sure the device is Android 7.0+ on ARM64. ③ APKs transferred via WeChat/QQ may be renamed or truncated — use USB/cloud storage instead. ④ On MIUI enable Developer options → "Install via USB". Since v0.5.0 the APK is signed with a dedicated release certificate (v2+v3 schemes, same cert for debug and release builds) for maximum installer compatibility.
“Environment extraction failed” on launch	Tap Retry; if it repeats, open ⚙ → Diagnostics & Environment to check free storage (>500 MB) and tap Reset environment.
App re-extracts the environment on every launch	Version mismatch: the built-in image .runtime-version must equal RUNTIME_IMAGE_VERSION in CodexServerManager.kt. Rebuild the image with build-image.py (v0.4.1+ aligns both).
Gradle build fails on another machine	Since v0.5.0 the repo no longer carries machine-specific config: you only need JDK 17 + Android SDK (sdk.dir in android/local.properties). Aliyun Maven mirrors and the Tencent Gradle mirror are built in — no proxy needed in mainland China.
Workspace starts but API calls fail	Check the key in ⚙ settings and that the device can reach the provider endpoint.

Roadmap & Docs

• ROADMAP.md — what is coming next
• workbench-audit-2026-09.md — workbench frontend audit vs 2026 agent standards (P0 gaps & fix plan)
• DESIGN.md — architecture rationale and trade-offs
• CHANGELOG.md — version history

Security & License

• Security: see SECURITY.md for the policy and how to report issues.
• License: MIT · bundled components listed in THIRD_PARTY_NOTICES.md.
• Disclaimer: this is an early-stage project. Verify generated code before running it, and keep your API keys private.