OmniBot: an on-device Android agent that runs Alpine and a terminal

The problem is that phone agents usually stop at chat

Most assistant apps on Android answer questions and then hand control back to you. OmniBot is aimed at the loop the README calls understand, decide, execute, reflect. That means the app is expected to act: run commands in a terminal, read and write files in a workspace, open a browser, set alarms and calendar entries, and play audio. The intended user is someone who wants an agent with hands on the device, not a chat window with a microphone button. The README frames the audience indirectly through the development guide: it assumes you can run Flutter, Gradle and pnpm, and it assumes you keep a computer and a phone on the same trusted LAN. This is a tool for people who already tinker with Android builds and local services, not for someone who wants to install an APK and never look at a terminal again.

How the pieces connect: Flutter UI, Kotlin host, Alpine, and a local service

The repository describes the app as built with native Android Kotlin and Flutter. The Flutter side lives in ui/, where you run flutter pub get. A separate React, TypeScript and Vite project lives in webchat/ and serves as the WebUI. The Android app exposes a local service; during development, Vite proxies /webchat/api requests to that service, which is how the browser frontend reaches sessions, realtime events, workspace access and browser mirroring. The default port is 8899, though the README says to always use the address the app displays. On the device, an Alpine environment provides the terminal side, and the README states the app usually initializes it automatically on startup, with manual management available in settings. Skills are installed by sending the app a repository link, and the README points to OpenMinis/MinisSkills as a recommended collection. There is also a remote Codex bridge: codex-bridge runs on a PC or Mac where the Codex CLI is installed and logged in, and the phone connects to it by scanning a QR code printed by that bridge. The data flow is therefore split across four surfaces: the phone UI, the on-device Alpine shell, the local HTTP service, and optionally a desktop Codex process.

Getting it running: pub get, pnpm, and a Gradle task that matters

The README lists Flutter SDK 3.9.2 or newer, JDK 11 or newer, and Node.js 20.19 or 22.12 with pnpm 10.28.0 for WebUI work. Cloning and preparing the Flutter side is two commands: git clone https://github.com/omnimind-ai/OpenOmniBot.git, then cd ui and flutter pub get. If Flutter complains about include_flutter.groovy, the documented fix is flutter clean followed by flutter pub get. For the WebUI, you install with pnpm install --frozen-lockfile and start the dev server with VITE_WEBCHAT_PROXY_TARGET set to the Android local-service address, for example http://192.168.1.20:8899, without appending /webchat. PowerShell users set $env:VITE_WEBCHAT_PROXY_TARGET first. Before submitting WebUI changes, the README requires pnpm run typecheck and pnpm run build, and it states that dist/ and node_modules/ must not be committed. The detail worth noticing is that Android builds handle the WebUI automatically: Gradle runs the locked pnpm install, executes the Vite production build, clears stale WebChat assets, and copies only dist/ into the APK. You can check that step in isolation with ./gradlew :app:syncWebChatBundle -Ptarget=lib/main_standard.dart. The README also says Flutter Web is not part of this workflow, which saves you from trying it.

The settings you cannot skip: models, embedding, and the Alpine environment

Configuration happens in the app, not in a config file. From the left sidebar you open settings, then AI capabilities, then AI providers, then the scenario model settings. The README is explicit that Memory embedding requires an embedding model, and that for the best overall experience the other scenarios should use multimodal or vision-capable models whenever possible. That is a real constraint rather than a suggestion: if you point the embedding scenario at a text-only or absent model, the memory system described in the core capabilities has nothing to embed with. The Alpine environment is managed from the same settings area, and the README notes the app usually initializes it automatically on startup. The word usually is doing a lot of work there. If your device blocks the initialization, the terminal and workspace features depend on that environment, so this is the first thing to confirm on your hardware before you plan around it.

What the README does not tell you

The documentation is uneven. The development guide is detailed enough to reproduce a build, including the proxy variable and the Gradle sync task. The operating guide is not. There is no description of how long a scheduled task runs, what happens when a subagent fails midway, or how memory is stored and pruned. The README says scheduled tasks execute subagent flows and that alarms are reminder-only, which is a useful distinction, but it does not say what a subagent's limits are. The licence metadata reports NOASSERTION, so the repository does not state its terms in the field most tools read; you have to open the licence files yourself before you depend on the code. The release notes are thin as well: the most recent entries are version numbers with one Chinese note about a Codex plan and confirmation fix, which tells you the project is iterating quickly but not what changed for users. None of this makes the project unusable. It means you should treat the README as build documentation and discover runtime behavior yourself.

Where OmniBot is the wrong choice

If you need a phone assistant that works without configuration, OmniBot will frustrate you. It expects you to supply model providers, an embedding model, and possibly a vision-capable model, and it expects you to keep a trusted LAN for the WebUI development path. If you need a documented, versioned API for other software to call, the material here describes a local service with a token and a default port of 8899, not a stable public interface. If you are building for iOS, the repository is Android only: the description names the Android world, and the build instructions are Gradle and APK oriented. And if your threat model does not allow an app with a terminal and file access on a personal phone, the whole design is against you. That is not a flaw in the project. It is a mismatch in use case, and it is worth naming before you spend a weekend on the build.

The alternative that changes the architecture, not just the app

The clearest contrast in the material is the codex-bridge path. Instead of running the agent entirely on the phone, you start npx @thuocean/codex-bridge on a computer where the Codex CLI is already installed and logged in, choose the LAN address and token mode in the terminal setup UI, and scan the printed QR code from OmniBot's Codex settings. That moves the heavy model work to a machine you control and leaves the phone as the interface and the executor. The difference in approach matters: on-device keeps your data on the device and works without a desktop, but it is bounded by phone hardware and by the models you can configure. The bridge gives you a desktop-class Codex session but requires a second computer, a shared network, and a token you have to manage. Neither is a superset of the other, and the README presents them as two modes rather than one recommended path, which is the honest framing.

Maintenance cost and what to check before you commit

The release cadence is fast. Three releases landed between September 8 and September 10, 2026, and the last push to the default branch matches the latest release date. Fast iteration is good for fixes and bad for stability: expect the build instructions and settings screens to move. Your upgrade cost is concentrated in three places. First, the Flutter and Gradle toolchain, since the README pins Flutter 3.9.2 or newer and JDK 11 or newer, and the WebUI requires Node.js 20.19 or 22.12 with pnpm 10.28.0. Second, the WebUI bundle, because Android builds re-run the locked pnpm install and the Vite build, so a lockfile change can surface at APK build time rather than in the webchat directory. Third, the licence, which the repository reports as NOASSERTION and which you should read directly rather than infer. Before adopting, verify that the Alpine environment initializes on your device, that your providers cover the embedding and vision scenarios, and that the local service reachable on port 8899 accepts the token from a second machine. If those three hold, the project does what its description claims.

Editorial conclusion

Adopt OmniBot if you want an agent that runs on the phone itself and you are willing to read the build scripts, because the README is stronger on Gradle tasks than on day-to-day operation. Do not adopt it if you need a stable, documented API or a licence you can read at a glance: the repository reports NOASSERTION, so the terms are not stated in the metadata and you have to check the actual licence files before shipping anything. Verify three things first: that the app initializes the Alpine environment on your device as the README says it usually does, that your chosen models satisfy the memory embedding and vision requirements, and that the local service address and token work from a second machine on the same LAN.

Official sources

1. Issues
2. omnimind-ai/OmniBot on GitHub
3. Project website
4. README
5. Releases