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

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

pkg install nodejs-lts

This satisfies the Node >=22 requirement defined in the repository’s package.json.

Step 2: Deploy OmniRoute via npx

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

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:

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 (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)

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:

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:

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 (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, 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 and 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:

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. All model providers, proxy configurations, and MCP/A2A endpoints function identically on Android via Termux.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}