https://github.com/criollojoel10/opencode-termux-native
OpenCode 1.14.25 natively compiled for Android 16 Termux - Production ready with documentation
https://github.com/criollojoel10/opencode-termux-native
aarch64 android opencode termux
Last synced: 28 days ago
JSON representation
OpenCode 1.14.25 natively compiled for Android 16 Termux - Production ready with documentation
- Host: GitHub
- URL: https://github.com/criollojoel10/opencode-termux-native
- Owner: criollojoel10
- License: other
- Created: 2026-04-26T02:21:15.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-04-26T16:19:09.000Z (about 1 month ago)
- Last Synced: 2026-04-26T18:13:51.196Z (about 1 month ago)
- Topics: aarch64, android, opencode, termux
- Language: Shell
- Size: 19.1 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenCode Native for Termux
> **Native OpenCode compilation and deployment for Termux on Android 16**
[](https://opensource.org/licenses/MIT)
[](https://www.android.com/)
[](https://en.wikipedia.org/wiki/AArch64)
[](https://github.com/anomalyco/opencode)
[](./DEPLOYMENT.md)
## Overview
This repository contains a **production-ready, fully tested compilation** of OpenCode for Termux on Android 16 devices. It includes:
- ✅ **Pre-compiled OpenCode 1.14.25** (aarch64/arm64-v8a)
- ✅ **Android 16 pointer tag truncation fixes** documented and tested
- ✅ **Full build reproducibility** with patches and procedures
- ✅ **Server deployment guides** with Bionic-specific optimizations
- ✅ **Troubleshooting reference** for Android 15/16 edge cases
- ✅ **Integration scripts** for CI/CD and system automation
### What This Solves
Running OpenCode natively on Termux/Android 16 introduces several challenges:
| Challenge | Solution | Reference |
|-----------|----------|-----------|
| **Pointer tag truncation crashes** | Unset `LD_PRELOAD` (termux-exec bug) | [Android MTE Docs](https://source.android.com/docs/core/architecture/tagged-pointers) |
| **Missing glibc in Termux** | Proper package management (glibc-repo flow) | [Termux glibc](https://wiki.termux.com/wiki/Glibc) |
| **seccomp blocking statx()** | OCT includes libstatx-shim.so | [OCT Docs](https://github.com/Hope2333/opencode-termux#statx-seccomp) |
| **16 KB page size incompatibility** | Bionic wrapper + runtime validation | [Android 16 Tech Guide](https://source.android.com/docs/core/architecture/16kb-page-size/optimize) |
| **Termux build environment** | Proper SHELL path and dependencies | [Termux Build Guide](./docs/TERMUX_BUILD_ENV.md) |
---
## Quick Start
### 1. Prerequisites
```bash
# Android 16 device with Termux installed
# Recommended: Fresh Termux environment with pkg update/upgrade
echo "Your device:"
getprop ro.build.version.release_or_codename # Should show "16"
getprop ro.product.cpu.abi # Should show "arm64-v8a"
getconf PAGE_SIZE # Note page size (4096 or 16384)
```
### 2. Install OpenCode
```bash
# Option A: Install pre-built package
pkg install -y glibc-repo glibc openssl-glibc
apt install -y ./opencode_1.14.25_aarch64.deb
# Option B: Rebuild from source (see COMPILATION.md)
make all VER=latest PKG=both ODIR=~/oct-out
```
### 3. Start Server
```bash
# CRITICAL: Unset LD_PRELOAD to avoid pointer tag truncation
env -u LD_PRELOAD opencode serve --port 4096 --hostname 0.0.0.0
# Expected output:
# Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.
# opencode server listening on http://0.0.0.0:4096
```
### 4. Verify
```bash
# From another terminal:
curl http://0.0.0.0:4096/api/health
```
---
## Repository Contents
```
opencode-termux-native/
├── README.md ← You are here
├── LICENSE ← MIT License
├── DEPLOYMENT.md ← Production deployment guide
├── COMPILATION.md ← Build procedures & patches
├── TROUBLESHOOTING.md ← Android 16 issues & fixes
├── ANDROID_16_NOTES.md ← Detailed Android 16 technical notes
│
├── dist/ ← Pre-built artifacts
│ ├── opencode_1.14.25_aarch64.deb
│ ├── opencode_1.14.25_aarch64.deb.sha256
│ └── HASHES.md
│
├── docs/ ← Documentation
│ ├── TERMUX_BUILD_ENV.md ← Setting up Termux correctly
│ ├── POINTER_TAGS_EXPLAINED.md ← MTE & pointer tag security
│ ├── 16KB_PAGE_SIZE.md ← Page size alignment issues
│ ├── SECCOMP_STATX.md ← statx() syscall blocking
│ ├── DEPLOYMENT_GUIDE.md ← Complete deployment walkthrough
│ └── INTEGRATION.md ← CI/CD integration examples
│
├── patches/ ← Build patches
│ ├── makefile-shell-path.patch
│ ├── produce-local-log-redirect.patch
│ └── PATCHES_APPLIED.md
│
├── scripts/ ← Utility scripts
│ ├── install.sh ← Automated installation
│ ├── verify.sh ← Verify installation & environment
│ ├── diagnostics.sh ← System diagnostics
│ ├── run-server.sh ← Start server with mitigations
│ ├── rebuild.sh ← Rebuild from OCT source
│ └── health-check.sh ← Monitor server health
│
├── test/ ← Test procedures
│ ├── test-pointer-tags.sh ← Verify pointer tag fix
│ ├── test-server-startup.sh ← Test server initialization
│ ├── test-page-size.sh ← Validate page size compatibility
│ └── RESULTS.md ← Test results on Android 16
│
├── examples/ ← Usage examples
│ ├── basic-server.md ← Simple server setup
│ ├── systemd-unit.md ← systemd integration (if available)
│ ├── pm2-setup.md ← Process manager integration
│ └── docker-alternative.md ← Container-based alternative
│
├── build-cache/ ← Build artifacts (for reference)
│ ├── oct-source/
│ ├── compilation-logs/
│ └── version-info/
│
└── .github/
├── workflows/
│ ├── verify.yml ← Verification workflow
│ └── release.yml ← Release automation
└── CONTRIBUTING.md ← Contributing guidelines
```
---
## Installation Methods
### Method 1: Quick Install (Pre-built)
```bash
# One-liner installation
bash <(curl -fsSL https://raw.githubusercontent.com/your-username/opencode-termux-native/main/scripts/install.sh)
```
### Method 2: Manual Installation
```bash
# 1. Update Termux
pkg update -y && pkg upgrade -y
# 2. Install dependencies
pkg install -y glibc-repo glibc openssl-glibc
# 3. Download & install package
wget https://github.com/your-username/opencode-termux-native/releases/download/v1.14.25/opencode_1.14.25_aarch64.deb
apt install -y ./opencode_1.14.25_aarch64.deb
# 4. Verify
opencode --version
```
### Method 3: Build from Source
```bash
# Clone OCT (opencode-termux)
git clone https://github.com/Hope2333/opencode-termux.git
cd opencode-termux
# Apply patches from this repo
git apply <(curl -fsSL https://raw.githubusercontent.com/your-username/opencode-termux-native/main/patches/makefile-shell-path.patch)
git apply <(curl -fsSL https://raw.githubusercontent.com/your-username/opencode-termux-native/main/patches/produce-local-log-redirect.patch)
# Compile
make all VER=latest PKG=both ODIR=~/oct-out
# Install
apt install -y ~/oct-out/deb/*.deb
```
---
## Deployment
### Development Server
```bash
env -u LD_PRELOAD opencode serve --port 4096 --hostname 127.0.0.1
```
### Production Server
```bash
# Set secure password
export OPENCODE_SERVER_PASSWORD="$(openssl rand -base64 32)"
# Run with PM2 or systemd
env -u LD_PRELOAD pm2 start "opencode serve --port 4096 --hostname 0.0.0.0" --name opencode
# Or with nohup
nohup env -u LD_PRELOAD opencode serve --port 4096 --hostname 0.0.0.0 > opencode.log 2>&1 &
```
See [DEPLOYMENT.md](./DEPLOYMENT.md) for advanced configurations.
---
## Android 16 Known Issues & Fixes
### Issue 1: Pointer Tag Truncation ⚠️
**Symptom**:
```
Pointer tag for 0x7f... was truncated
SIGSEGV / Segmentation fault
```
**Root Cause**: `libtermux-exec-ld-preload.so` truncates ARM64 MTE pointer tags on Android 16
**Fix**:
```bash
# Always use:
env -u LD_PRELOAD opencode ...
# NOT:
opencode ... # ❌ Will crash
```
**Reference**: [POINTER_TAGS_EXPLAINED.md](./docs/POINTER_TAGS_EXPLAINED.md)
---
### Issue 2: 16 KB Page Size
**Detection**:
```bash
getconf PAGE_SIZE # Returns 16384 (instead of 4096)
```
**Current Status**:
- ✅ OCT Bionic wrapper handles most cases
- ✅ Tested and verified on Android 16
- ⚠️ If custom NDK binaries fail, may need recompilation with NDK 28+
**Reference**: [16KB_PAGE_SIZE.md](./docs/16KB_PAGE_SIZE.md)
---
### Issue 3: seccomp / statx() Blocking
**Symptom**:
```
SIGSYS: seccomp denied
statx() not available
```
**Fix**: OCT includes `libstatx-shim.so` (automatic, no action needed)
**Test**:
```bash
OPENCODE_DISABLE_STATX_SHIM=1 opencode --version # Should fail
env -u LD_PRELOAD opencode --version # Should work
```
**Reference**: [SECCOMP_STATX.md](./docs/SECCOMP_STATX.md)
---
## System Information
### Test Environment
| Property | Value |
|----------|-------|
| **Device** | Android 16 (AOSP build) |
| **Architecture** | aarch64 (arm64-v8a) |
| **Termux Version** | Latest (as of 2026-04-25) |
| **OpenCode Version** | 1.14.25 |
| **Compilation Date** | 2026-04-25 |
| **Build Method** | OCT (opencode-termux by Hope2333) |
| **Package Manager** | apt (Debian-based) |
### Pre-installed Dependencies
```
glibc: 2.42
openssl-glibc: 3.4.1
clang: 21.1.8
cmake: 3.3.2
ninja: 1.13.2
rust: 1.95.0
python: 3.x
```
---
## Verification & Testing
### Automated Tests
```bash
# Run all tests
bash test/test-pointer-tags.sh
bash test/test-server-startup.sh
bash test/test-page-size.sh
# Or use the verification script
bash scripts/verify.sh
```
### Manual Verification
```bash
# 1. Check binary
opencode --version
# Expected: 1.14.25
# 2. Check environment
bash scripts/diagnostics.sh
# 3. Start server (30-second test)
timeout 30 env -u LD_PRELOAD opencode serve --port 4096 --hostname 0.0.0.0
# 4. Test connectivity (from another terminal)
curl http://0.0.0.0:4096/api/health
```
### Test Results
See [test/RESULTS.md](./test/RESULTS.md) for detailed test results on Android 16.
---
## Build Information
### Compilation Details
- **Route**: OCT (opencode-termux by Hope2333)
- **Upstream Binary**: opencode-linux-arm64 1.14.25
- **Runtime Wrapper**: bun-termux-loader (Bionic compatible)
- **Shims Included**:
- libstatx-shim.so (seccomp mitigation)
- bunfs_shim.so (4 KB)
- **Total Package Size**: 33 MB
- **Build Duration**: ~5-10 minutes on Android 16
### Patches Applied
1. **Makefile SHELL Path** - `/bin/bash` → `$PREFIX/bin/bash`
2. **Log Function Redirect** - stdout → stderr (avoid variable capture)
See [patches/PATCHES_APPLIED.md](./patches/PATCHES_APPLIED.md) for details.
---
## Contributing
Found issues? Have improvements? See [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md)
### Development Setup
```bash
git clone https://github.com/your-username/opencode-termux-native.git
cd opencode-termux-native
# Create a feature branch
git checkout -b feature/your-feature
# Test your changes
bash scripts/verify.sh
bash test/*.sh
# Submit PR
git push origin feature/your-feature
```
---
## Troubleshooting
### Common Issues
| Issue | Solution | Docs |
|-------|----------|------|
| Pointer tag truncation | Use `env -u LD_PRELOAD` | [ANDROID_16_NOTES.md](./ANDROID_16_NOTES.md) |
| Server won't start | Check diagnostics | [scripts/diagnostics.sh](./scripts/diagnostics.sh) |
| Permission denied | Fix Termux PREFIX | [TERMUX_BUILD_ENV.md](./docs/TERMUX_BUILD_ENV.md) |
| Package install fails | Update glibc-repo | [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) |
| 16 KB page size errors | See page size guide | [16KB_PAGE_SIZE.md](./docs/16KB_PAGE_SIZE.md) |
See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for complete reference.
---
## Related Projects
- **[OpenCode](https://github.com/anomalyco/opencode)** - The official open-source coding agent
- **[OCT (opencode-termux)](https://github.com/Hope2333/opencode-termux)** - OpenCode packaging for Termux
- **[Termux](https://github.com/termux/termux-app)** - Terminal emulator for Android
- **[bun-termux-loader](https://github.com/Hope2333/bun-termux-loader)** - Bionic runtime wrapper
---
## Performance & Benchmarks
See [DEPLOYMENT.md](./DEPLOYMENT.md#benchmarks) for performance metrics on Android 16.
**Quick Stats**:
- **Startup Time**: ~2-3 seconds
- **Memory Usage**: ~150-200 MB (baseline)
- **Server Response Time**: <100ms (average)
- **Concurrent Connections**: Tested with 5+ clients
---
## License
This project and compiled artifacts are licensed under the **MIT License**. See [LICENSE](./LICENSE) file.
OpenCode itself is licensed under its own terms - see [anomalyco/opencode LICENSE](https://github.com/anomalyco/opencode/blob/main/LICENSE).
---
## Support & Contact
- 📖 **Documentation**: See `/docs` folder
- 🐛 **Bug Reports**: GitHub Issues
- 💬 **Discussions**: GitHub Discussions
- 📧 **Contact**: [GitHub Profile]
---
## Acknowledgments
- **Hope2333** - OCT (opencode-termux) project
- **Anomaly Co** - OpenCode official project
- **Termux Project** - Terminal emulator and build environment
- **Android Open Source Project** - Technical documentation
---
## Changelog
### v1.14.25 (2026-04-25) - Initial Release
- ✅ OpenCode 1.14.25 compilation for Android 16
- ✅ Pointer tag truncation mitigation documented & tested
- ✅ Full build reproducibility with patches
- ✅ Comprehensive documentation & guides
- ✅ Automated installation & verification scripts
- ✅ Android 16 compatibility verified
---
**Last Updated**: 2026-04-25
**Status**: ✅ Production Ready
**Tested On**: Android 16 (aarch64)