Skip to main content

Termux & Lightweight Devices

Mercury runs on Android via Termux, giving you a real coding agent in your pocket. It also works in other minimal environments like iSH (iOS), Alpine containers, and Raspberry Pi.

Termux (Android)​

Requirements​

  • Android 7.0+
  • Termux installed from F-Droid or GitHub Releases (the Play Store build is unmaintained — do not use it)
  • ~500 MB free storage for Node.js, Mercury, and native module compilation
  • Network access

Install Node.js + Mercury​

Termux is the recommended path on Android because the prebuilt Linux binaries target glibc, while Termux uses bionic libc. Use the npm route:

pkg update && pkg upgrade -y
pkg install nodejs-lts git python make clang pkg-config -y
npm i -g @cosmicstack/mercury-agent
mercury

nodejs-lts provides Node 20+ and npm. Python, Make, Clang, and pkg-config are required when npm needs to build native dependencies such as better-sqlite3 for Android's bionic libc. Do not use Mercury's standalone Linux binary on Termux.

Let Mercury read/write files in your Android storage:

termux-setup-storage
# grants ~/storage/ symlinks: ~/storage/shared, ~/storage/downloads, etc.

Now you can point Mercury at projects in ~/storage/shared/Projects/....

Keep Mercury running in the background​

Android may stop Termux processes when the app is swiped away or the device sleeps. For the best available background behavior:

  1. Install Termux:API and Termux:Boot from the same source as Termux (F-Droid or GitHub), then install the API commands:

    pkg install termux-api
    termux-wake-lock

  2. Disable battery optimization for Termux in Settings → Apps → Termux → Battery.

  3. Start Mercury with its supported daemon command:

    mercury start

Termux does not run systemd, so mercury service install is intentionally unsupported. To request startup after reboot, create ~/.termux/boot/start-mercury:

mkdir -p ~/.termux/boot
cat > ~/.termux/boot/start-mercury <<'EOF'
#!/data/data/com.termux/files/usr/bin/sh
termux-wake-lock
mercury start
EOF
chmod +x ~/.termux/boot/start-mercury

Termux:Boot only runs after the user has opened its app once, and Android/OEM background restrictions can still stop Mercury. A wakelock reduces suspension but increases battery use; release it with termux-wake-unlock when Mercury is stopped. This setup cannot guarantee server-like 24/7 availability.

See Daemon Mode for mercury start, mercury status, and mercury stop details.

Telegram bot on the go​

A common Termux setup: run Mercury's Telegram integration on your phone so you can chat with it from any device.

mercury doctor   # enable Telegram, paste bot token
mercury start

Known limitations​

  • No prebuilt binary — must use npm. The standalone installer (install.sh) won't work on Termux because of glibc/bionic differences.
  • No system service manager — systemd service install/status/uninstall is unavailable. Use Mercury's daemon commands and optionally Termux:Boot.
  • No guaranteed background uptime — wakelocks and Termux:Boot cannot override every Android or OEM process-killing policy.
  • TUI rendering — Mercury's interface assumes a wide terminal. Rotate landscape or pair Termux with an external keyboard for the best experience.
  • Background limits — Aggressive OEMs (Xiaomi, Oppo, Huawei) need extra battery-optimization tweaks beyond the standard Android settings.
  • Storage permission — Required for accessing project files outside $HOME.

Updating​

mercury upgrade

…or:

npm i -g @cosmicstack/mercury-agent@latest

iSH (iOS)​

iSH runs an Alpine Linux user-space on iOS. Mercury works there via npm:

apk add nodejs npm
npm i -g @cosmicstack/mercury-agent
mercury

Performance is limited — iSH emulates x86 via usermode, so expect slow startup. Best used for read-only / chat-style sessions.

Alpine Linux / minimal containers​

Alpine uses musl libc, so the standalone Linux binary won't load. Use npm:

apk add --no-cache nodejs npm git
npm i -g @cosmicstack/mercury-agent

This applies to Docker images based on alpine:* as well.

Raspberry Pi​

  • 64-bit Pi OS (Pi 3/4/5): the standard Linux installer works — pulls mercury-linux-arm64.

  • 32-bit Pi OS or armv6 (Pi Zero, Pi 1): no prebuilt binary; install via npm:

    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt install -y nodejs
    npm i -g @cosmicstack/mercury-agent

Other lightweight environments​

If your platform isn't listed and the binary doesn't run (Exec format error, missing libc), the npm route always works as long as Node.js 20+ is available. If Node isn't packaged for your OS, see Build From Source.

Next steps​