Skip to content

docs: add Android (Termux) install guide - #62695

Open
jason081112 wants to merge 4 commits into
anomalyco:devfrom
jason081112:termux-docs
Open

jason081112 wants to merge 4 commits into
anomalyco:devfrom
jason081112:termux-docs

Conversation

@jason081112

@jason081112 jason081112 commented Nov 8, 2026 •

Copy link
Copy Markdown

Issue for this PR

Closes #

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Adds an Android (Termux) page to the V2 docs and links it from the CLI install section.

The Linux ARM64 build is a glibc ELF and Termux is Bionic, so it does not run as shipped. The page documents the setup I verified on aarch64: install glibc and patchelf, point the ELF interpreter at Termux's loader, and wrap the binary in a launcher that clears LD_PRELOAD.

Two details are worth calling out because they are easy to get wrong:

  • Only the interpreter should be patched. --set-rpath (what grun -c does) rewrites the executable and corrupts its bundled payload, which shows up as SIGSEGV or libc.so: invalid ELF header. Termux's loader already searches $PREFIX/glibc/lib.
  • Running 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. Running the patched binary directly avoids it.

The page is marked community-maintained, so it does not claim official Android support.

How did you verify your code works?

On Termux aarch64 with Android 15 and @opencode/cli-linux-arm64:

  • opencode --version prints the release version
  • opencode service status returns the background service URL
  • The TUI starts and connects to the background service
  • The launcher works while the parent shell still has Termux's LD_PRELOAD set

I also checked that the standalone opencode-linux-arm64.tar.gz from the update API requests /lib/ld-linux-aarch64.so.1, so the same patch applies to the download path the page uses.

Screenshots / recordings

N/A. New page only.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Added by the opencode bot (AI-generated).

Related: #47612, #60762

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The page is clear and fits the V2 docs conventions: frontmatter, supported Callout types, root-relative links and the sidebar entry all look right. I didn't run anything because this is docs only and I have no Termux device, so the steps themselves are your testing, not mine. I also checked that the updater won't detect a binary under ~/.local/lib/opencode, so auto-update won't overwrite the patched binary. That matches the manual update section.

Public API: unchanged.

One inconsistency to fix in the troubleshooting table (inline comment).

For maintainers: this documents an unofficial workaround in the official docs, which is your call. The draft #60903 would add a native android-arm64 build, and if it lands this page should be removed or rewritten.

Related: #47612, #60762

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This row says libc.so: invalid ELF header comes from a leftover LD_PRELOAD. The "Patch the interpreter only" warning above (and your PR description) says the same error comes from setting an RPATH. If both can cause it, please list both fixes here: re-extract and patch only the interpreter, or check the launcher. Otherwise someone who ran grun -c will keep checking their launcher.

@jason081112

Copy link
Copy Markdown
Author

Fixed in a3b2236. The libc.so: invalid ELF header row now lists both causes with the matching fix: an RPATH written by grun -c, or a leftover LD_PRELOAD pointing at the Bionic shim.

On the maintainer call: agreed, this is a workaround, and the page says community-maintained in its first callout. If #60903 lands, I'm happy to delete the page or rewrite it as a note on the native android-arm64 build.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My earlier point is fixed: the troubleshooting row for libc.so: invalid ELF header now lists both causes and their fixes, so it matches the "Patch the interpreter only" warning. Nothing new from me. The public API is unchanged.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant