Termux-focused packaging and runtime workflow for OpenCode.

Use one package-manager path per machine.

Recommended for most clean Termux test machines.

apt install -y glibc-repo
apt update
apt install -y glibc openssl-glibc
apt install -y /path/to/opencode_<version>_aarch64.deb

Optional fallback tooling:

apt install -y glibc-runner

Use this only when your Termux environment is already pacman-based.

pacman -Syu
pacman -S glibc openssl-glibc
pacman -U /path/to/opencode-<version>-aarch64.pkg.tar.xz

Optional fallback tooling:

pacman -S glibc-runner

opencode --version
opencode --help
opencode web

This repository is part of the OML/OCT track and focuses on:

• reproducible OpenCode runtime packaging on real Termux devices
• consistent deb + pacman package outputs from one staged prefix
• safer launcher defaults for Termux runtime behavior
• plugin lifecycle support (install/update/rollback/patch)

• Verified runtime line: OpenCode Runtime (Android/Bionic wrapped)
• Final packages are produced locally on Termux
• GitHub Actions is used for armv7 cross-prebuild handoff only (non-mainline/deferred track)

• ✅ Mainline Termux packaging flow (deb + pacman) is operational
• ✅ machine1(build) -> local relay -> machine2(test) lifecycle is validated
• ✅ plugin/system-skill hook framework phase-2 is implemented and tested (registry + compatibility gates + blocklist)
• ✅ read-only diagnostics and matrix simulation are available (make selfcheck, make matrix)
• 🚧 Next: OML parent orchestration targets and richer plugin policy controls

1. Expand matrix scenarios to cross-version ranges with archived logs per run.
2. Add registry inspection/reporting commands for system skills and hook outcomes.
3. Add policy presets for controlled networked plugin auto-update on machine1 only.
4. Tighten GNU/Linux secondary build validation while preserving Termux-first guarantees.

• Mainline (maintained in this repo)
  • local Termux build/package flow (make, tools/produce-local.sh, scripts/package/*)
  • dependency policy and runtime stability improvements
  • docs and operational runbooks under docs/
• Deferred / non-mainline
  • arm32 adaptation and migration experiments
  • broad armv7 portability work beyond handoff artifacts

Deferred items may be referenced in docs/history but are not release-blocking for the mainline workflow.

• scripts/ - local build + package scripts
• packaging/ - package metadata/templates
• tools/ - helper tools (produce-local.sh, plugin-manager.sh)
• docs/ - canonical documentation and runbooks

Start here: docs/README.md

Workflow: .github/workflows/prebuild-armv7.yml

CI prepares cross-toolchain evidence + handoff templates/artifacts. It does not claim final Termux runtime compatibility.

Use real Termux environment for final runtime wrapping and package generation.

Typical flow:

./tools/produce-local.sh <version>
./scripts/build.sh
./scripts/package/package_deb.sh
./scripts/package/package_pacman.sh

Use package-manager-driven plugin strategy + local recoverability tools.

See:

• docs/plugin-packaging-design.md
• docs/plugin-management.md

Installed launcher includes:

• TTY cleanup on exit
• stale lock cleanup
• broken plugin cache cleanup
• OPENCODE_DISABLE_DEFAULT_PLUGINS=1 default

Maintainer/packager identity defaults to:

Hope2333(幽零小喵) <[email protected]>

• Does not use musl as the final Termux runtime path
• Does not use proot as official build path
• Does not treat CI artifacts as final Termux release binaries
• Default package hard dependency is glibc; glibc-runner is optional fallback tooling for compatibility/troubleshooting

• Glibc dependency reduction report: docs/glibc-min-deps-test-report.md
• Upgrade/downgrade simulation helper: tools/upgrade-matrix.sh
• Read-only plugin/environment self-check: tools/plugin-selfcheck.sh
• External plugin builder project (main route): https://github.com/Hope2333/opencode-plugins-termux
• System skill manifests (package mode): packaging/manifests/system-skills/
• Hook runner (package mode): scripts/hooks/run-system-skills.sh
• System-skill architecture: docs/system-skills-hook-architecture.md
• Runtime build details: docs/13-opencode-runtime-build.md
• Package docs: docs/20-packaging-deb.md, docs/21-packaging-pkg-tar-xz.md
• CI armv7 handoff: docs/ci-prebuild-armv7.md
• Execution checklist: docs/execution-checklist.md
• Incident RCA (.so restart snowball): docs/incidents/2026-02-23-opencode-web-termux-so-avalanche.md

• Upstream OpenCode: https://github.com/anomalyco/opencode
• This packaging workflow repository follows upstream license constraints for redistributed artifacts.

You can orchestrate full local build/package flow with Make targets or wrapper flags.

Examples:

make all VER=<version> PKG=both
make all VER=latest PKG=pacman
make batch VERS='<major.minor.[start-end]>' PKG=deb ODIR=~/oct-out
./tools/make-opencode --all --ver <version> --pkg pacman
./tools/make-opencode --batch --vers '<version1> <version2>' --pkg both --odir ~/oct-out
./tools/make-opencode --all --ver <version> --pkg both --odir ~/oct-out --mix

Rules:

• tools/produce-local.sh version priority:
  1. first positional argument (explicit version)
  2. latest opencode-linux-arm64 from npm (if no version passed)
• if npm package for requested version is unavailable, fallback downloads GitHub release binary (opencode-linux-arm64.tar.gz) for that version.
• work directory defaults to project-local .work/ (instead of $HOME/work-*), and is auto-cleaned unless KEEP_WORK=1.
• Packaging targets auto-clean generated work dirs before running to reduce stale contamination.
• Pacman package version is derived from staged runtime (.../runtime/opencode --version) instead of hardcoded pkgver.
• Package metadata now uses required glibc + openssl-glibc; glibc-runner is optional fallback tooling (Suggests/optdepends). Current validated network-minimal set (for opencode run "hi"): glibc + openssl-glibc.
• Package-mode system skill hooks are non-interactive and fail-soft by default:
  • OPENCODE_HOOK_STRICT=0
  • OPENCODE_HOOK_ENABLE_NETWORK=0
  • this avoids silent plugin auto-install/update during package install/upgrade.
• Phase-2 gate/registry support:
  • compatibility gates (minimum_core_version / maximum_core_version / blocklists)
  • system registry at $PREFIX/share/opencode/system-skills-registry.json
• output policy:
  • default output root is project packing/
  • if ODIR is set, outputs go to ODIR and do not use project packing/
  • default classified layout: deb/ and pacman/ subfolders
  • if MIX=1 or --mix, artifacts are flattened into one directory

• Upgrade/downgrade simulation using cached deb artifacts only:

TARGET_HOST=192.168.1.22 TARGET_USER=u0_a258 \
make matrix VERS='<old_version> <new_version>' ODIR=~/oct-out

or direct script call:

VERS='<old_version> <new_version>' ODIR=~/oct-out \
TARGET_HOST=192.168.1.22 TARGET_USER=u0_a258 \
./tools/upgrade-matrix.sh

• Read-only self-check (no mutation):

make selfcheck

• single version, classified output in project:
• make all VER=<version> PKG=both
• single version, custom output root:
• make all VER=<version> PKG=both ODIR=~/oct-out
• batch versions with range and flat output:
  • make batch VERS='1.1.[1-20]' PKG=deb ODIR=~/oct-out MIX=1

Launcher now preserves normal exit summaries better:

• successful exits use soft tty cleanup (keeps session/restore output visible)
• signal/error exits still use full tty cleanup for safety