# How to Run OmniRoute on Android Using Termux: Complete Installation Guide

> Install OmniRoute on Android with Termux easily. Follow our guide to run this powerful tool natively on your device using a simple npx command. Get started now!

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-04

---

**OmniRoute runs natively on Android via Termux using a single npx command, with automatic headless mode detection and ARM-compatible SQLite compilation.**

OmniRoute is a pure-Node.js AI gateway that deploys anywhere Node.js runs, including Android smartphones via the Termux terminal emulator. According to the `diegosouzapw/OmniRoute` source code, the repository includes a dedicated Termux guide at [`docs/guides/TERMUX_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/TERMUX_GUIDE.md) that enables a full headless deployment on mobile devices without platform-specific modifications.

## Prerequisites for Termux Deployment

Before installing OmniRoute, ensure your Android environment meets the base requirements. The project’s [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) specifies **Node.js >=22**, which is available through Termux’s LTS package.

- Install Termux from F-Droid or the Play Store
- Install Node.js LTS: `pkg install nodejs-lts`
- (Optional) Install Termux API for additional Android utilities: `pkg install termux-api`

## Installing OmniRoute on Android

The installation process leverages the Node.js ecosystem to download and execute the latest CLI release without manual cloning.

### Step 1: Install Node.js LTS

```bash
pkg install nodejs-lts

```

This satisfies the Node >=22 requirement defined in the repository’s [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json).

### Step 2: Deploy OmniRoute via npx

Execute the official one-liner to fetch and start the gateway:

```bash
npx -y omniroute

```

This command pulls the latest CLI from npm and immediately starts the server on the default port 3000.

### Step 3: Verify the Installation

Confirm the server is responding by querying the models endpoint:

```bash
curl http://127.0.0.1:3000/api/v1/models

```

A successful response returns the JSON model catalog, confirming that OmniRoute is operational on your Android device.

## Headless Mode and Android Auto-Detection

As implemented in `diegosouzapw/OmniRoute`, the core architecture detects Android environments automatically and suppresses browser launching. This **headless mode** is essential for 24×7 phone-based proxy deployments where no display is available.

- The auto-detection logic is documented in [`CHANGELOG.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/CHANGELOG.md) (lines 2507–2580)
- No manual `--headless` flags are required on Android
- The CLI implementation in `src/cli/**/*.ts` handles platform detection via `commander` argument parsing

## Running OmniRoute as a Background Service

To keep the gateway alive across screen locks and reboots, use a process manager like `pm2` or Termux’s built-in `sv` utility.

### Using pm2 (Recommended)

```bash
npm i -g pm2
pm2 start "$(which omniroute)" --name omni
pm2 save

```

This configuration persists the OmniRoute process across Termux sessions and device restarts.

### Using Termux Services

Alternatively, use Termux’s service infrastructure:

```bash
sv up omniroute

```

## Compiling SQLite for ARM Architecture

The `better-sqlite3` native module requires compilation from source on Termux’s ARM64 environment. The repository includes build-time tweaks via `GYP_DEFINES` to facilitate this process.

If the automatic installation fails, manually rebuild the native module:

```bash
export GYP_DEFINES="CPPFLAGS=-I$HOME/.termux/usr/include LDFLAGS=-L$HOME/.termux/usr/lib"
npm rebuild better-sqlite3

```

Additionally, the project declares `wreq-js` and `tls-client-node` as **optional dependencies** specifically for ARM devices, as noted in [`CHANGELOG.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/CHANGELOG.md) (line 4240). These modules provide enhanced networking capabilities when available but are not required for core functionality.

## Android Architecture and File Locations

OmniRoute operates identically to its desktop counterpart, with paths resolving to Termux’s sandboxed filesystem:

- **CLI Entry**: The `npx omniroute` command invokes the wrapper described in [`bin/cli/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/bin/cli/README.md), which launches the Next.js server stack
- **Data Directory**: SQLite databases and configuration store in `~/.omniroute/`, which resolves to `/data/data/com.termux/files/home/.omniroute/` on Android
- **Networking**: Outbound provider traffic routes through [`open-sse/utils/proxyDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyDispatcher.ts) and [`open-sse/utils/proxyFamily.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyFamily.ts), using Termux’s standard TCP stack without platform-specific modifications
- **MCP/A2A APIs**: All agent-facing endpoints remain available locally, allowing Android-hosted agents to drive OmniRoute directly

## Provider Configuration Example

Once the server is running, configure providers using the standard CLI syntax:

```bash
omniroute provider add openai \
  --api-key sk-xxxxxxxxxxxxxxxx \
  --model gpt-4o-mini

```

All commands function identically to Linux or macOS deployments because the CLI is built on the platform-agnostic `commander` library.

## Summary

- **OmniRoute on Android** requires only Termux and Node.js LTS (>=22) to operate
- **Installation** is handled via `npx -y omniroute`, which auto-detects Android and runs in headless mode
- **Database support** requires compiling `better-sqlite3` from source using `GYP_DEFINES` on ARM64
- **Persistence** is achieved through `pm2` or Termux’s `sv` service manager
- **Architecture** remains identical to desktop—same CLI, same APIs, same `open-sse` networking stack

## Frequently Asked Questions

### Does OmniRoute require root access on Android?

No. OmniRoute runs entirely within Termux’s user-space environment, requiring no root privileges or system-level modifications. All file operations occur within Termux’s sandboxed home directory at `/data/data/com.termux/files/home/`.

### Can I run OmniRoute in the background on Android?

Yes. Use `pm2` to daemonize the process with `pm2 start "$(which omniroute)" --name omni`, or utilize Termux’s `sv` service manager. These methods keep the gateway alive even when the Termux app is not in the foreground or when the screen is locked.

### Why does better-sqlite3 need manual compilation on Termux?

Termux uses a non-standard Android toolchain and ARM64 architecture that differs from typical Linux distributions. The `better-sqlite3` module contains native C++ bindings that must be compiled against Termux’s specific headers and libraries, which is facilitated by setting `GYP_DEFINES` with the correct include and library paths.

### Is the Android version limited compared to the desktop version?

No. The Android deployment is functionally identical to desktop versions. The only difference is the automatic headless mode detection that suppresses browser launching, as documented in [`CHANGELOG.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/CHANGELOG.md). All model providers, proxy configurations, and MCP/A2A endpoints function identically on Android via Termux.