From 67812e1b6da2dc63ec88065bbd29891cd912d5d4 Mon Sep 17 00:00:00 2001 From: Brajesh <138358890+Brajesh2022@users.noreply.github.com> Date: Fri, 22 May 2026 16:33:00 +0530 Subject: [PATCH] Add Termux setup guide --- README.md | 5 + docs/termux.md | 718 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 723 insertions(+) create mode 100644 docs/termux.md diff --git a/README.md b/README.md index aeff0f6bf..b73662f7b 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ Antigravity CLI understands your codebase, makes edits with your permission, and - **Official Docs**: [antigravity.google/docs/cli-overview](https://antigravity.google/docs/cli-overview) - **Official Website**: [antigravity.google/product/antigravity-cli](https://antigravity.google/product/antigravity-cli) +- **Termux Setup**: [Running Antigravity CLI on Termux](docs/termux.md) ![Antigravity CLI Demo](agy-cli-demo.gif) @@ -39,6 +40,10 @@ Antigravity CLI brings the core capabilities of Antigravity 2.0 (multi-step reas curl -fsSL https://antigravity.google/cli/install.sh | bash ``` +### Android Termux + +For Android Termux, see [Running Antigravity CLI on Termux](docs/termux.md). + ### Windows PowerShell ```powershell irm https://antigravity.google/cli/install.ps1 | iex diff --git a/docs/termux.md b/docs/termux.md new file mode 100644 index 000000000..c9778e35e --- /dev/null +++ b/docs/termux.md @@ -0,0 +1,718 @@ +# Running Antigravity CLI on Termux + +This document describes the working setup for running the native Antigravity CLI (`agy`) on Android Termux. + +The main goal is to run the official Linux ARM64 Antigravity binary directly from Termux without Cloud Shell, without a full VM, and without replacing Android. The setup uses a small binary patch plus a wrapper that adapts the Linux/glibc binary to Termux's Android environment. + +The method is designed to be repeatable for future Antigravity releases. The patch script scans instruction patterns instead of relying on fixed offsets. If Antigravity changes its allocator code generation in the future, the script will print warning counts instead of silently claiming success. + +## What This Fixes + +Antigravity's Linux ARM64 binary can fail on Termux for multiple independent reasons. + +The working setup fixes these problems: + +1. TCMalloc assumes a 48-bit ARM64 userspace virtual address space. +2. Many Android/Termux devices expose only a 39-bit userspace virtual address layout. +3. Android seccomp can block Go's `faccessat2` syscall and kill the process with `SIGSYS`. +4. Termux's `LD_PRELOAD` can inject a Bionic preload library into the glibc binary. +5. The glibc environment may try to load `libc.so`, but Termux glibc's `libc.so` is a linker script, not an ELF shared object. +6. Go's DNS resolver inside the glibc-loaded binary may not find the correct Android/Termux resolver config. +7. TLS verification can fail unless the Termux CA bundle is exposed through `SSL_CERT_FILE`. +8. Shell command hashing can keep pointing at an old `agy`, so the shortcut clears the shell hash before launching. + +## Expected Final Layout + +After setup, the important files are: + +```text +~/.local/bin/agy # original official Antigravity binary, left unchanged +~/.local/bin/agy.va39 # patched binary generated by the script +~/.local/bin/agy-va39 # wrapper used to launch the patched binary +~/.local/lib/agy-glibc/libc.so +~/.local/lib/agy-glibc/libc.so.6 +~/patch_agy_va39.py # reusable patch script +``` + +The user-facing commands are: + +```bash +agy +a +agy-va39 +``` + +`agy` and `a` should both run the `agy-va39` wrapper. + +## Requirements + +Install or verify these tools in Termux: + +```bash +pkg update +pkg install python proot curl ca-certificates +``` + +You also need a Termux-compatible glibc installation that provides these files: + +```text +/data/data/com.termux/files/usr/glibc/lib/ld-linux-aarch64.so.1 +/data/data/com.termux/files/usr/glibc/lib/libc.so.6 +``` + +Verify them: + +```bash +test -x /data/data/com.termux/files/usr/glibc/lib/ld-linux-aarch64.so.1 +test -f /data/data/com.termux/files/usr/glibc/lib/libc.so.6 +``` + +You also need the official Linux ARM64 `agy` binary installed at: + +```text +~/.local/bin/agy +``` + +Verify the binary exists: + +```bash +test -x ~/.local/bin/agy +file ~/.local/bin/agy +``` + +The `file` output should identify it as an ARM64 Linux ELF binary. + +## Step 0: Install the Official Antigravity CLI Binary + +Skip this step if `~/.local/bin/agy` already exists. + +Run the official install script: + +```bash +curl -fsSL https://antigravity.google/cli/install.sh | bash +``` + +## Step 1: Create the Generalized VA39 Patch Script + +Create `~/patch_agy_va39.py`: + +```python +#!/usr/bin/env python3 +""" +Generalized VA39 patch for the agy linux_arm64 binary. + +Based on hjotha's analysis in: +https://github.com/google-antigravity/antigravity-cli/issues/64 + +This scans instruction patterns instead of using fixed offsets, so it can work +across builds where the relevant TCMalloc code moved. +""" + +import hashlib +import shutil +import struct +import sys +from pathlib import Path + + +src = Path(sys.argv[1] if len(sys.argv) > 1 else str(Path.home() / ".local/bin/agy")) +dst = Path(str(src) + ".va39") + +if not src.exists(): + raise SystemExit(f"Input binary does not exist: {src}") + +print(f"Input binary : {src}") +print(f"SHA256 in : {hashlib.sha256(src.read_bytes()).hexdigest()}") +print() + +shutil.copyfile(src, dst) +data = bytearray(dst.read_bytes()) + + +def get(off): + return struct.unpack_from(" #35,#3 and lsl #42 -> #35. +# These move TCMalloc's tag extraction/insertion from bit 42 to bit 35. +ubfx_count = 0 +lsl_count = 0 +for off in range(lo, hi, 4): + w = get(off) + if (w & 0x7F800000) == 0x53000000: # bitfield-move family + immr = (w >> 16) & 0x3F + imms = (w >> 10) & 0x3F + if immr == 42 and imms == 44: # ubfx Xn, Xm, #42, #3 + put(off, (w & ~((0x3F << 16) | (0x3F << 10))) | (35 << 16) | (37 << 10)) + ubfx_count += 1 + elif immr == 22 and imms == 21: # lsl Xn, Xm, #42 encoded as lsr + put(off, (w & ~((0x3F << 16) | (0x3F << 10))) | (29 << 16) | (28 << 10)) + lsl_count += 1 + +print(f"[1] ubfx patches : {ubfx_count} (expect ~15)") +print(f" lsl patches : {lsl_count} (expect ~2)") + +# 3. Random address mask pairs. +# mov x10, #-0x6c00000001; movk x10, #0, lsl #48 +# -> mov x10, #-1; lsr x10, x10, #29 +# Gives x10 = 0x7ffffffff, a 39-bit address mask. +mask_count = 0 +for off in range(lo, hi - 4, 4): + if get(off) == 0x92D3800A and get(off + 4) == 0xF2E0000A: + put(off, 0x9280000A) + put(off + 4, 0xD35DFD4A) + mask_count += 1 + +print(f"[2] Random mask : {mask_count} (expect ~3)") + +# 4. MmapAlignedLocked upper bound: 1 << 48 -> 1 << 39. +mmap_count = 0 +for off in range(lo, hi, 4): + if get(off) == 0xF2E00029: + put(off, 0xD3596129) + mmap_count += 1 + +print(f"[3] MmapAligned : {mmap_count} (expect ~1)") + +# 5. Inlined tag constants and fast-path deallocation masks. +# Move tag placement from bit 42 to bit 35. +word_rewrites = { + 0xD2C20009: 0xD2C00409, # normal P0 tag x9: 4 << 42 -> 4 << 35 + 0xD2C2000A: 0xD2C0040A, # normal P0 tag x10 + 0xF2C20008: 0xF2DFF408, # normal dealloc mask x8 + 0xF2C20009: 0xF2DFF409, # normal dealloc mask x9 + 0xD2C10009: 0xD2C00209, # cold tag x9: 2 << 42 -> 2 << 35 + 0xD2C1000A: 0xD2C0020A, # cold tag x10 + 0xF2C38008: 0xF2DFF708, # cold/tagged dealloc mask x8 + 0xF2C38009: 0xF2DFF709, # cold/tagged dealloc mask x9 + 0x92560A6C: 0x925D0A6C, # tag mask 0x1c0000000000 -> 0x3800000000 x12 + 0x92560A6A: 0x925D0A6A, # tag mask x10 + 0xD2C3000D: 0xD2C0060D, # normal P1 tag x13: 6 << 42 -> 6 << 35 + 0xD2C3000C: 0xD2C0060C, # normal P1 tag x12 + 0xD2C08008: 0xD2C00108, # kTagFree: 1 << 42 -> 1 << 35 +} +counts = {old: 0 for old in word_rewrites} +for off in range(lo, hi, 4): + w = get(off) + if w in word_rewrites: + put(off, word_rewrites[w]) + counts[w] += 1 + +print(f"[4] Tag constants: {sum(counts.values())} words rewritten") + +# 6. Android/Termux syscall compatibility. +# Go's faccessat2 syscall can be killed by Android seccomp with SIGSYS. The +# old faccessat syscall is enough for os/exec.LookPath checks on Termux. +faccessat2_count = 0 +for off in range(0, len(data) - 12, 4): + if ( + get(off) == 0xAA1F03E5 + and get(off + 4) == 0xAA1F03E6 + and get(off + 8) == 0xD28036E0 + and (get(off + 12) & 0xFC000000) == 0x94000000 + ): + put(off + 8, 0xD2800600) # mov x0, #48; syscall.SYS_FACCESSAT + faccessat2_count += 1 + +print(f"[5] faccessat2 : {faccessat2_count} syscall wrapper rewritten") + +dst.write_bytes(data) +dst.chmod(0o755) + +out_sha = hashlib.sha256(dst.read_bytes()).hexdigest() +print() +print(f"SHA256 out : {out_sha}") +print(f"Output : {dst}") +print() + +total = ubfx_count + lsl_count + mask_count + mmap_count + sum(counts.values()) + faccessat2_count +if total == 0: + print("WARNING: No patches applied - binary structure may have changed.") + print("Do NOT use the output binary.") +elif ubfx_count == 0 or mask_count == 0: + print("WARNING: Some expected patches were not found.") + print("The patch may be incomplete - test carefully.") +else: + print("Patch looks complete. Now test with:") + print() + print(" GLIBC=/data/data/com.termux/files/usr/glibc/lib") + print(" $GLIBC/ld-linux-aarch64.so.1 --library-path $GLIBC \\") + print(f" {dst} --version") +``` + +Make it executable: + +```bash +chmod +x ~/patch_agy_va39.py +``` + +## Step 2: Patch the Official Binary + +Run the script against the original official binary: + +```bash +python3 ~/patch_agy_va39.py ~/.local/bin/agy +``` + +The script creates: + +```text +~/.local/bin/agy.va39 +``` + +The original binary remains unchanged: + +```text +~/.local/bin/agy +``` + +Healthy output should show nonzero patch counts. On the tested build, the counts were: + +```text +[1] ubfx patches : 15 + lsl patches : 2 +[2] Random mask : 3 +[3] MmapAligned : 1 +[4] Tag constants: 108 words rewritten +[5] faccessat2 : 1 syscall wrapper rewritten +``` + +Future builds may have different tag constant counts, but these are important signs: + +```text +ubfx patches should not be 0 +Random mask should not be 0 +MmapAligned should usually be nonzero +faccessat2 may be 0 if Go or the binary changed +``` + +If the script says no patches were applied, do not use the generated output. + +## Step 3: Create the glibc `libc.so` Shim + +Some parts of the program or its dependencies may try to load `libc.so` dynamically. In the Termux glibc layout, `libc.so` can be an ASCII linker script instead of an ELF shared object. glibc's dynamic loader rejects that with `invalid ELF header`. + +Create a tiny shim directory where both `libc.so` and `libc.so.6` point to the real ELF library: + +```bash +mkdir -p ~/.local/lib/agy-glibc +ln -sfn /data/data/com.termux/files/usr/glibc/lib/libc.so.6 ~/.local/lib/agy-glibc/libc.so +ln -sfn /data/data/com.termux/files/usr/glibc/lib/libc.so.6 ~/.local/lib/agy-glibc/libc.so.6 +``` + +Verify: + +```bash +file ~/.local/lib/agy-glibc/libc.so +file /data/data/com.termux/files/usr/glibc/lib/libc.so.6 +``` + +`libc.so` in the shim should be a symlink to the real `libc.so.6`. + +## Step 4: Create the Termux Wrapper + +Create `~/.local/bin/agy-va39`: + +```sh +#!/data/data/com.termux/files/usr/bin/sh +G=/data/data/com.termux/files/usr/glibc/lib +S=/data/data/com.termux/files/home/.local/lib/agy-glibc +unset LD_PRELOAD +unset LD_LIBRARY_PATH +export GODEBUG=netdns=go +export SSL_CERT_FILE=/data/data/com.termux/files/usr/etc/tls/cert.pem +exec /data/data/com.termux/files/usr/bin/proot \ + -b /data/data/com.termux/files/usr/etc/resolv.conf:/etc/resolv.conf \ + $G/ld-linux-aarch64.so.1 --library-path $S:$G \ + /data/data/com.termux/files/home/.local/bin/agy.va39 "$@" +``` + +Make it executable: + +```bash +chmod +x ~/.local/bin/agy-va39 +``` + +Why each line matters: + +```text +G points to the Termux glibc loader and libraries. +S points to the shim directory where libc.so resolves to libc.so.6. +unset LD_PRELOAD prevents Termux's Bionic preload from entering a glibc process. +unset LD_LIBRARY_PATH prevents host Termux library paths from polluting glibc resolution. +GODEBUG=netdns=go forces Go's pure DNS resolver. +SSL_CERT_FILE points TLS verification at Termux's CA bundle. +proot binds Termux's resolver config into /etc/resolv.conf for the glibc program. +--library-path $S:$G makes glibc search the shim first, then the real glibc libs. +``` + +## Step 5: Add Shell Shortcuts + +Make sure `~/.local/bin` is in `PATH`. Add this near the top of `~/.bashrc` if it is not already present: + +```bash +export PATH="$HOME/.local/bin:$HOME/bin:$PATH" +``` + +Add these functions to `~/.bashrc`: + +```bash +agy() { + hash -r + agy-va39 "$@" +} + +a() { + hash -r + agy-va39 "$@" +} +``` + +Reload the shell config: + +```bash +source ~/.bashrc +``` + +The `hash -r` line clears Bash's command lookup cache. This matters when `agy` previously pointed at a different binary, alias, or wrapper. + +## Step 6: Verify the Setup + +Check the wrapper directly: + +```bash +agy-va39 --version +``` + +Check the shortcuts: + +```bash +agy --version +a --version +``` + +Then start the interactive CLI: + +```bash +agy +``` + +If `agy` starts but complains about login or authentication, the native binary is running. At that point the remaining issue is account/auth flow, not the Termux compatibility layer. + +## Updating Antigravity Later + +When a new Antigravity release is installed, the official binary at `~/.local/bin/agy` may be replaced. Repeat only the patch step: + +```bash +python3 ~/patch_agy_va39.py ~/.local/bin/agy +``` + +Then test: + +```bash +agy-va39 --version +agy --version +``` + +The wrapper usually does not need to change after an Antigravity update. + +If future Antigravity releases include an official VA39-compatible Linux ARM64 build, the TCMalloc patch may no longer be needed. The Termux wrapper may still be useful for glibc, DNS, certificates, and preload cleanup. + +## Problems Encountered and the Working Fixes + +### 1. TCMalloc failed before startup + +Observed error: + +```text +MmapAligned() failed - unable to allocate with tag +TCMalloc assumes a 48-bit virtual address space size +FATAL ERROR: Out of memory trying to allocate internal tcmalloc data +``` + +Cause: + +```text +The binary was built with TCMalloc constants for a 48-bit ARM64 userspace VA. +Many Android/Termux devices use a 39-bit userspace VA layout. +TCMalloc generated mmap hints above the address range accepted by the kernel. +``` + +Working fix: + +```text +Patch TCMalloc's inlined address/tag constants from bit 42 to bit 35. +Patch the random mmap address mask to 39 bits. +Patch the MmapAligned upper bound from 1 << 48 to 1 << 39. +Patch tag/deallocation masks, not only RandomMmapHint. +``` + +### 2. `SIGSYS: bad system call` from `faccessat2` + +Observed error: + +```text +SIGSYS: bad system call +syscall.faccessat2 +os/exec.findExecutable +``` + +Cause: + +```text +Go used the newer faccessat2 syscall. Android seccomp blocked it. +The kernel killed the process with SIGSYS before the CLI could continue. +``` + +Working fix: + +```text +Patch the Go syscall wrapper from faccessat2 syscall 439 to older faccessat syscall 48. +``` + +This is included in `patch_agy_va39.py`. + +### 3. `invalid ELF header` for glibc `libc.so` + +Observed error: + +```text +error while loading shared libraries: /data/data/com.termux/files/usr/glibc/lib/libc.so: invalid ELF header +``` + +Cause: + +```text +The file named libc.so in the Termux glibc directory can be a linker script, not an ELF shared object. +The runtime loader or a dlopen path needed an actual shared object. +``` + +Working fix: + +```text +Create ~/.local/lib/agy-glibc/libc.so as a symlink to glibc's real libc.so.6. +Put that shim directory before the glibc lib directory in --library-path. +``` + +### 4. `LIBC not found` from `libtermux-exec-ld-preload.so` + +Observed error: + +```text +version `LIBC' not found (required by /data/data/com.termux/files/usr/lib/libtermux-exec-ld-preload.so) +``` + +Cause: + +```text +Termux can set LD_PRELOAD to inject libtermux-exec-ld-preload.so. +That library is built for Android's Bionic libc, not glibc. +Preloading it into a glibc process breaks symbol/version resolution. +``` + +Working fix: + +```sh +unset LD_PRELOAD +unset LD_LIBRARY_PATH +``` + +These lines are in the wrapper before invoking the glibc loader. + +### 5. DNS looked up `oauth2.googleapis.com` through `[::1]:53` + +Observed behavior: + +```text +lookup oauth2.googleapis.com on [::1]:53 +``` + +Cause: + +```text +The glibc-loaded binary did not see Termux's resolver config at /etc/resolv.conf. +On this setup, /etc/resolv.conf did not exist, while Termux's resolver file existed at: +/data/data/com.termux/files/usr/etc/resolv.conf +``` + +Working fix: + +```text +Use proot to bind Termux's resolver file into /etc/resolv.conf for the launched process. +Force Go's pure resolver with GODEBUG=netdns=go. +``` + +Wrapper lines: + +```sh +export GODEBUG=netdns=go +exec /data/data/com.termux/files/usr/bin/proot \ + -b /data/data/com.termux/files/usr/etc/resolv.conf:/etc/resolv.conf \ + ... +``` + +### 6. TLS verification failed after DNS worked + +Cause: + +```text +The glibc process did not automatically know where Termux's CA certificate bundle lives. +``` + +Working fix: + +```sh +export SSL_CERT_FILE=/data/data/com.termux/files/usr/etc/tls/cert.pem +``` + +Verify the file exists: + +```bash +test -f /data/data/com.termux/files/usr/etc/tls/cert.pem +``` + +### 7. `agy` command still pointed at the wrong thing + +Cause: + +```text +Bash caches command paths. Existing aliases or old command lookups can persist in a running shell. +``` + +Working fix: + +```bash +agy() { + hash -r + agy-va39 "$@" +} + +a() { + hash -r + agy-va39 "$@" +} +``` + +## Quick Health Checks + +Use these commands when debugging: + +```bash +type agy +type a +type agy-va39 +``` + +```bash +agy-va39 --version +agy --version +a --version +``` + +```bash +file ~/.local/bin/agy +file ~/.local/bin/agy.va39 +file /data/data/com.termux/files/usr/glibc/lib/libc.so +file /data/data/com.termux/files/usr/glibc/lib/libc.so.6 +``` + +```bash +test -f /data/data/com.termux/files/usr/etc/resolv.conf +test -f /data/data/com.termux/files/usr/etc/tls/cert.pem +``` + +```bash +curl -I https://oauth2.googleapis.com +``` + +If `curl` works but `agy` has DNS or TLS errors, check the wrapper's `GODEBUG`, `proot` bind, and `SSL_CERT_FILE` lines. + +## Known Caveats + +This is still a binary patch. It is practical, but it is not as robust as an official VA39-compatible build. + +The correct upstream fix would be one of these: + +```text +Build the Linux ARM64 binary with TCMALLOC_ADDRESS_BITS=39. +Provide a runtime VA-aware TCMalloc configuration. +Provide a non-TCMalloc Linux ARM64 binary. +Provide an official Android/Termux-compatible build. +``` + +The patch script is intentionally conservative. If expected instruction patterns disappear, do not assume the output is safe. Re-check the binary, update the pattern scanner, or wait for an official build. + +## Minimal Repeat Workflow + +For future Antigravity updates, the short version is: + +```bash +curl -fsSL https://antigravity.google/cli/install.sh | bash +python3 ~/patch_agy_va39.py ~/.local/bin/agy +chmod +x ~/.local/bin/agy.va39 +agy-va39 --version +agy --version +``` + +If `agy-va39` already exists and the wrapper has not been changed, you usually do not need to recreate the wrapper or shell functions. + +## Final Working Wrapper + +Keep this as the known-good wrapper: + +```sh +#!/data/data/com.termux/files/usr/bin/sh +G=/data/data/com.termux/files/usr/glibc/lib +S=/data/data/com.termux/files/home/.local/lib/agy-glibc +unset LD_PRELOAD +unset LD_LIBRARY_PATH +export GODEBUG=netdns=go +export SSL_CERT_FILE=/data/data/com.termux/files/usr/etc/tls/cert.pem +exec /data/data/com.termux/files/usr/bin/proot \ + -b /data/data/com.termux/files/usr/etc/resolv.conf:/etc/resolv.conf \ + $G/ld-linux-aarch64.so.1 --library-path $S:$G \ + /data/data/com.termux/files/home/.local/bin/agy.va39 "$@" +```