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` |