| 1 | # Termux / Android arm64 Support |
| 2 | |
| 3 | Codewhale provides an Android arm64 build and archive path for |
| 4 | [Termux](https://termux.dev). Treat v0.9.1 support as a preview until the |
| 5 | real-device runtime QA tracked in #4236 and #4242 is complete. This document |
| 6 | covers the install path and the platform-specific behavior differences you |
| 7 | should know about. |
| 8 | |
| 9 | ## Installation |
| 10 | |
| 11 | See [`INSTALL.md`](./INSTALL.md) → "Android / Termux arm64" for the current |
| 12 | install steps. The short version: |
| 13 | |
| 14 | ```sh |
| 15 | # Inside Termux (pkg install rust git ...) |
| 16 | cargo install codewhale-cli --locked |
| 17 | cargo install codewhale-tui --locked |
| 18 | ``` |
| 19 | |
| 20 | Or, when a release includes `codewhale-android-arm64.tar.gz`, extract it |
| 21 | into `$PREFIX/bin`. |
| 22 | |
| 23 | > **Do not** install the GNU libc `codewhale-linux-arm64` archive in Termux. |
| 24 | > Android uses Bionic libc, not glibc — the Linux binary will not run. |
| 25 | |
| 26 | ## Platform behavior on Android |
| 27 | |
| 28 | Codewhale's security model has three distinct layers on Android: |
| 29 | |
| 30 | 1. **Android's app sandbox** — Android assigns Termux its own app UID and |
| 31 | applies the platform's SELinux and seccomp protections. Commands started by |
| 32 | Codewhale inherit that app boundary and any storage or other permissions the |
| 33 | user has granted to Termux. See the |
| 34 | [Android application sandbox](https://source.android.com/docs/security/app-sandbox) |
| 35 | and [Termux filesystem layout](https://github.com/termux/termux-packages/wiki/Termux-file-system-layout). |
| 36 | 2. **Codewhale's per-command sandbox backend** — Seatbelt (macOS) or the |
| 37 | opt-in bubblewrap wrapper (Linux) can further narrow what a child command |
| 38 | may access. Codewhale does not currently provide that additional layer on |
| 39 | Android. |
| 40 | 3. **Codewhale's own gates** — workspace trust, approval prompts, |
| 41 | `allow_shell`/`disallowed-tools`, and the file-tool permission system. |
| 42 | These share the cross-platform application code path; their Android |
| 43 | behavior still needs the real-device QA tracked below. |
| 44 | |
| 45 | ### Codewhale sandbox backend: none |
| 46 | |
| 47 | Codewhale's existing Seatbelt and Linux bubblewrap integrations do not target |
| 48 | Android. Consequently, `codewhale doctor --json` reports the sandbox as |
| 49 | `{"available": false, "kind": null}` on Android. That status describes the |
| 50 | absence of an additional Codewhale child-process sandbox; it does not mean |
| 51 | Android or Termux provides no OS isolation. |
| 52 | |
| 53 | - `get_platform_sandbox()` returns `None` on Android. |
| 54 | - No Linux-only bubblewrap wrapper is compiled into the Android build — it is |
| 55 | `#[cfg(target_os = "linux")]`-gated and Rust |
| 56 | treats `android` as a distinct target from `linux`. |
| 57 | - Shell commands retain Termux's Android app boundary but receive no |
| 58 | Codewhale-specific filesystem narrowing. Treat every location available to |
| 59 | Termux, including user-granted shared storage, as potentially available to a |
| 60 | command that you approve. |
| 61 | |
| 62 | ### Approvals: still apply |
| 63 | |
| 64 | Codewhale's approval system (interactive prompts for risky actions, |
| 65 | `allow_shell`, `--disallowed-tools`) is implemented at the application layer, |
| 66 | independently of the OS sandbox. The Android code path is present, but its |
| 67 | interactive behavior still needs the real-device QA tracked in #4242. |
| 68 | |
| 69 | ### Secret storage: file-backed |
| 70 | |
| 71 | Codewhale's Termux/native build has no supported OS keyring backend (the |
| 72 | desktop Secret Service/dbus integration is unavailable, and Codewhale does not |
| 73 | yet integrate [Android Keystore](https://developer.android.com/privacy-and-security/keystore)). |
| 74 | It therefore falls back to **file-backed secret storage**: plaintext JSON files under |
| 75 | `~/.codewhale/secrets/` (Termux home directory), protected only by `0600` |
| 76 | file permissions — they are **not encrypted at rest**. On single-user |
| 77 | Termux this uses the same Unix permission mode as `~/.ssh` private keys; it is |
| 78 | not encrypted at rest. |
| 79 | |
| 80 | - Keys saved through setup, `/provider`, or `codewhale auth set` are written to |
| 81 | `~/.codewhale/config.toml` and mirrored to |
| 82 | `~/.codewhale/secrets/secrets.json`. Treat both as plaintext sensitive |
| 83 | files. |
| 84 | - `codewhale auth status --provider <id>` reports which secret backend is |
| 85 | active for a provider. |
| 86 | |
| 87 | ### Self-update |
| 88 | |
| 89 | `codewhale update` on Android requests `codewhale-android-arm64` and |
| 90 | `codewhale-tui-android-arm64` release assets — never the Linux arm64 |
| 91 | assets. The GNU libc (glibc) compatibility preflight is Linux-only and is |
| 92 | skipped entirely on Android (Bionic libc). |
| 93 | |
| 94 | ## Known limitations (first Termux release) |
| 95 | |
| 96 | | Feature | Status | Notes | |
| 97 | |---------|--------|-------| |
| 98 | | Android app sandbox | ✅ inherited | Per-app UID plus Android platform protections | |
| 99 | | Codewhale command sandbox | ❌ unavailable | No bubblewrap/Seatbelt backend on Android | |
| 100 | | Codewhale keyring backend | ❌ unavailable | Falls back to file-backed secrets | |
| 101 | | Approvals / gates | ⚠️ implemented | Device QA pending | |
| 102 | | File tools | ⚠️ implemented | Device QA pending | |
| 103 | | Self-update | ⚠️ asset selection implemented | Published-asset and device QA pending | |
| 104 | | Shell execution | ⚠️ app boundary only | No Codewhale-specific narrowing; runtime QA pending | |
| 105 | |
| 106 | ## Related issues |
| 107 | |
| 108 | - #4236 — Epic: official Termux / Android arm64 support |
| 109 | - #4238 — Make Android sandbox and secret-store behavior explicit |
| 110 | - #4240 — Build and bundle Android arm64 release assets |
| 111 | - #4241 — Teach updater to select Android assets on Termux |
| 112 | - #4242 — Run Termux runtime QA |
| 113 |