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