Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

5.6 KB
Raw Blame
---
id: termux
title: Termux & Lightweight Devices
sidebar_label: Termux & Mobile
---

Mercury runs on **Android via [Termux](https://termux.dev/)**. Other lightweight environments require a compatible Node.js 22+ build and Mercury dependencies; availability varies by operating system and CPU.

## Termux (Android)

### Requirements

- Android 7.0+
- Termux installed from **[F-Droid](https://f-droid.org/en/packages/com.termux/)** or **[GitHub Releases](https://github.com/termux/termux-app/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:**

```bash
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 22+ (required since 1.3.1) 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.

### Storage access (optional but recommended)

Let Mercury read/write files in your Android storage:

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

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

   ```bash
   mercury start
   ```

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

```bash
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](../../daemon-mode/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](../../integrations/telegram) on your phone so you can chat with it from any device.

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

```bash
mercury upgrade
```

…or:

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

## iSH (iOS)

[iSH](https://ish.app/) runs an Alpine Linux user-space on iOS. Its emulated x86 environment is not covered by Mercury's standalone releases. Only try the npm route if Node.js 22+ and the dependencies are available:

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

```sh
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](./linux.mdx) works — pulls `mercury-linux-arm64`.
- **32-bit Pi OS or armv6 (Pi Zero, Pi 1)**: no prebuilt binary. The npm route requires a compatible Node.js 22+ build for the device and may require compiling native dependencies. Do not install Node.js 20 as a fallback; it does not meet Mercury's minimum version.

## Other lightweight environments

If a binary reports `Exec format error` or a missing libc, check the [standalone support limits](../installation.mdx#standalone-support-limits). The npm route requires Node.js 22+ and compatible dependencies; it is not guaranteed on unlisted systems. [Building from source](../build-from-source) also requires a compatible runtime.

## Next steps

- [Setup](../setup)
- [Telegram integration](../../integrations/telegram) — control Mercury from anywhere
- [Daemon Mode](../../daemon-mode/daemon-mode) — keep it running 24/7