From ac2084b10618f071af23dfb144212aa21965c252 Mon Sep 17 00:00:00 2001 From: Jason Wang <58059436+jason081112@users.noreply.github.com> Date: Sun, 8 Nov 2026 12:51:02 +0800 Subject: [PATCH 1/4] docs: add Android (Termux) install guide --- services/site/src/docs/content/cli/termux.mdx | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 services/site/src/docs/content/cli/termux.mdx diff --git a/services/site/src/docs/content/cli/termux.mdx b/services/site/src/docs/content/cli/termux.mdx new file mode 100644 index 000000000000..abb0d12b79b8 --- /dev/null +++ b/services/site/src/docs/content/cli/termux.mdx @@ -0,0 +1,112 @@ +--- +title: "Android (Termux)" +description: "Run the Linux ARM64 build on Android with Termux, glibc, and a patched ELF interpreter." +--- + +OpenCode has no Android build. The Linux ARM64 build runs under Termux once its ELF interpreter points at Termux's glibc and a small launcher clears the Bionic `LD_PRELOAD` that Termux sets. + + + This page is community-maintained. The steps are verified on Termux aarch64 with the `linux-arm64` release. + + +## Install the glibc runtime + +Termux uses Bionic, so the glibc runtime and `patchelf` come from separate packages: + +```bash +pkg update +pkg install glibc-repo +pkg update +pkg install glibc-runner patchelf +``` + +Check that the loader is present before continuing: + +```bash +ls "$PREFIX/glibc/lib/ld-linux-aarch64.so.1" +``` + +## Install and patch the binary + +Download the standalone Linux ARM64 archive: + +```bash +mkdir -p "$HOME/.local/lib/opencode" +curl -fsSL https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-arm64.tar.gz \ + -o "$TMPDIR/opencode.tar.gz" +tar -xzf "$TMPDIR/opencode.tar.gz" -C "$HOME/.local/lib/opencode" +``` + +Point the interpreter at Termux's glibc: + +```bash +patchelf --set-interpreter "$PREFIX/glibc/lib/ld-linux-aarch64.so.1" \ + "$HOME/.local/lib/opencode/opencode" +``` + +Confirm the result: + +```bash +patchelf --print-interpreter "$HOME/.local/lib/opencode/opencode" +``` + +``` +/data/data/com.termux/files/usr/glibc/lib/ld-linux-aarch64.so.1 +``` + + + Termux's glibc already searches `$PREFIX/glibc/lib` by default, so an RPATH is unnecessary. Setting one rewrites the + whole executable and can corrupt its bundled payload, which surfaces as `SIGSEGV` or `libc.so: invalid ELF header`. + Skip `grun -c` for the same reason. + + +## Add a launcher + +Termux exports `LD_PRELOAD=$PREFIX/lib/libtermux-exec-ld-preload.so`. That library is built for Bionic and crashes the +glibc loader, so clear it in the launcher: + +```bash +cat > "$PREFIX/bin/opencode" <<'EOF' +#!/data/data/com.termux/files/usr/bin/bash +unset LD_PRELOAD +exec "$HOME/.local/lib/opencode/opencode" "$@" +EOF +chmod 755 "$PREFIX/bin/opencode" +``` + + + Run the patched binary directly. Starting it through `grun` or `ld.so` makes `/proc/self/exe` the loader, so the + background service's re-exec fails with `serve: error while loading shared libraries: serve`. + + +## Verify + +```bash +opencode --version +opencode service status +``` + +`service status` prints the background service URL, for example `http://127.0.0.1:49374`. + +## Update + +Download the new archive over the existing binary and patch it again. The launcher stays the same. + +```bash +curl -fsSL https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-arm64.tar.gz \ + -o "$TMPDIR/opencode.tar.gz" +tar -xzf "$TMPDIR/opencode.tar.gz" -C "$HOME/.local/lib/opencode" +patchelf --set-interpreter "$PREFIX/glibc/lib/ld-linux-aarch64.so.1" \ + "$HOME/.local/lib/opencode/opencode" +opencode --version +``` + +## Troubleshooting + +| Symptom | Cause | Fix | +| --- | --- | --- | +| `serve: error while loading shared libraries: serve` | Started through `grun` or `ld.so`, so the service cannot re-exec itself | Run the launcher from [Add a launcher](#add-a-launcher) | +| `libc.so: invalid ELF header` | `LD_PRELOAD` still points at Termux's Bionic shim | Make sure the launcher runs `unset LD_PRELOAD` | +| `Segmentation fault` on `opencode --version` | The binary was patched with `--set-rpath`, for example by `grun -c` | Re-extract the archive and patch the interpreter only | +| `Permission denied` | The extracted file is not executable | `chmod 755 ~/.local/lib/opencode/opencode` | +| `error while loading shared libraries: ld-linux-aarch64.so.1` | The glibc runtime is missing | `pkg install glibc-repo glibc-runner` | From 497014bba2b704431be04d9e9501e762dacfdb37 Mon Sep 17 00:00:00 2001 From: Jason Wang <58059436+jason081112@users.noreply.github.com> Date: Sun, 8 Nov 2026 12:51:04 +0800 Subject: [PATCH 2/4] docs: list Android (Termux) in the CLI sidebar --- services/site/src/docs/lib/navigation.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/services/site/src/docs/lib/navigation.ts b/services/site/src/docs/lib/navigation.ts index 578970e15602..7afbda9c06e5 100644 --- a/services/site/src/docs/lib/navigation.ts +++ b/services/site/src/docs/lib/navigation.ts @@ -75,6 +75,7 @@ export const docsSections: DocsSection[] = [ { title: "Theme", slug: "cli/theme" }, { title: "Plugins", slug: "cli/plugins" }, { title: "Keybinds", slug: "cli/keybinds" }, + { title: "Android (Termux)", slug: "cli/termux" }, ], }, ], From 78c2355bc09698d0ef69509e140ebdbede8b593e Mon Sep 17 00:00:00 2001 From: Jason Wang <58059436+jason081112@users.noreply.github.com> Date: Sun, 8 Nov 2026 12:51:05 +0800 Subject: [PATCH 3/4] docs: link the Android (Termux) guide from the intro --- services/site/src/docs/content/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/services/site/src/docs/content/index.mdx b/services/site/src/docs/content/index.mdx index 6c349199e3cb..a8757e480503 100644 --- a/services/site/src/docs/content/index.mdx +++ b/services/site/src/docs/content/index.mdx @@ -37,6 +37,8 @@ Download a standalone CLI binary for your platform. - **Linux (glibc):** [ARM64](https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-arm64.tar.gz) · [x64](https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-x64.tar.gz) · [x64 (baseline)](https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-x64-baseline.tar.gz) - **Linux (musl):** [ARM64](https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-arm64-musl.tar.gz) · [x64](https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-x64-musl.tar.gz) · [x64 (baseline)](https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-x64-baseline-musl.tar.gz) +Android requires extra setup; see [Android (Termux)](/cli/termux). + ## Desktop Download the latest OpenCode Desktop build for your platform. From a3b223689eb44487c9f45b0e5622b438161028a8 Mon Sep 17 00:00:00 2001 From: Jason Wang <58059436+jason081112@users.noreply.github.com> Date: Sun, 8 Nov 2026 12:55:14 +0800 Subject: [PATCH 4/4] docs: list both causes of the invalid ELF header error --- services/site/src/docs/content/cli/termux.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/services/site/src/docs/content/cli/termux.mdx b/services/site/src/docs/content/cli/termux.mdx index abb0d12b79b8..8905cad7fee7 100644 --- a/services/site/src/docs/content/cli/termux.mdx +++ b/services/site/src/docs/content/cli/termux.mdx @@ -106,7 +106,7 @@ opencode --version | Symptom | Cause | Fix | | --- | --- | --- | | `serve: error while loading shared libraries: serve` | Started through `grun` or `ld.so`, so the service cannot re-exec itself | Run the launcher from [Add a launcher](#add-a-launcher) | -| `libc.so: invalid ELF header` | `LD_PRELOAD` still points at Termux's Bionic shim | Make sure the launcher runs `unset LD_PRELOAD` | +| `libc.so: invalid ELF header` | The binary was patched with `--set-rpath` (for example by `grun -c`), or `LD_PRELOAD` still loads Termux's Bionic shim | Re-extract the archive and patch the interpreter only, and make sure the launcher clears `LD_PRELOAD` | | `Segmentation fault` on `opencode --version` | The binary was patched with `--set-rpath`, for example by `grun -c` | Re-extract the archive and patch the interpreter only | | `Permission denied` | The extracted file is not executable | `chmod 755 ~/.local/lib/opencode/opencode` | | `error while loading shared libraries: ld-linux-aarch64.so.1` | The glibc runtime is missing | `pkg install glibc-repo glibc-runner` |