OpenMinis: an on-device AI agent with a Linux shell, reviewed for adoption

What OpenMinis solves, and who it is actually for

Most agent tooling assumes a server. You give it a container, a VM or a cloud sandbox, and the agent works there while your phone is just a client. OpenMinis inverts that. The README describes it as "Your private, on-device AI agent", and the architecture backs the phrase: a sandboxed Alpine Linux environment runs on the device itself, so the agent can install packages, run scripts and touch real files without a remote host. That single decision defines the audience. It is for people who want agent work to happen on hardware they hold, and who accept the constraints that come with it.

The second half of the pitch is device integration. Health, Calendar, Reminders, Contacts, HomeKit, Bluetooth, Clipboard, Media and Alarms are exposed to the agent as tools. That is not something a cloud agent can do at all, and it is where the concrete examples in the README live: photographing a meal and writing calories and macros to Apple Health, pulling a Telegram group's messages into Apple Reminders, or turning a shared page into a calendar event through the iOS Share Sheet.

The model layer is bring-your-own. Claude, GPT, Gemini and other providers are reachable through your own API keys or account sign-in. OpenMinis does not resell inference, which is consistent with the project being free and fully open source.

Who it is not for is worth stating plainly. If your work is long-running batch processing, or you need an agent that keeps going when the phone is locked and in a pocket, the on-device premise is working against you. The README does not claim background execution as a feature.

How the sandbox, skills and workspaces fit together

The repository layout makes the split visible. src/ios/ holds the Swift and SwiftUI app plus share, widget and file-provider extensions. src/android/ holds the Kotlin and Compose app with JNI native code. src/shared/ carries assets used by both. deps/ holds native dependency build scripts and vendored sources, and scripts/ handles rootfs preparation and developer tooling. That is a two-front-end, one-concept arrangement rather than a shared cross-platform core.

The sandbox is the load-bearing piece. On iOS it is iSH, Linux usermode emulation, run through an ARM64 fork the project maintains. On Android it is PRoot, a user-space chroot, again via a project fork, with talloc as a dependency. Alpine provides the userland. Because the agent gets a shell, it can install packages and run scripts, which is the difference between an agent that describes an action and one that performs it.

Skills are the extension mechanism, and the design is deliberately lazy. A skill is a folder containing a SKILL.md file with instructions and optionally scripts, references and assets. The README states that metadata stays in context for triggering, while the body and bundled resources load only when the skill is actually used. That is a context-budget decision, and a sensible one: a large skill library does not crowd out the conversation until a skill is relevant.

The interoperability claim is the interesting part. Minis has its own tool system, but the README says skills built for Claude, Codex, OpenClaw or Hermes Agent generally run in Minis as-is, and that skills adapted to Minis' tools run better because they can reach the Linux shell, device integrations and native offloads directly. Read that as an honest statement of a gradient rather than a compatibility guarantee. The README does not enumerate which third-party skills fail to trigger.

Workspaces organise work into separate contexts, addressable through the minis://workspace/ scheme. Persistent memory carries across sessions. Native offloads hand heavy or platform-specific work to native code instead of the sandbox, which is the escape hatch for anything the emulated or chrooted environment handles badly.

Installing OpenMinis and running a first agent task

There are two paths, and they are genuinely different products in terms of effort. The first is to install the app: the README links to the App Store listing for iOS and to the GitHub releases page for the Android APK, and notes that the TestFlight build receives fixes and new features before App Store releases because App Store updates wait on review. If you only want to use OpenMinis, stop there and skip the build.

The second path is building from source, which the README treats as the normal case for contributors because the native dependencies are not committed as binaries. iSH, PRoot, FFmpeg and LAME, plus the Alpine rootfs, are all built from source. Start with the clone, including submodules, since the dependency sources are vendored that way:

git clone --recurse-submodules https://github.com/OpenMinis/OpenMinis.git
cd OpenMinis

For iOS, the README is explicit that order matters because FFmpeg links against LAME. Run the dependency scripts in sequence, then prepare the rootfs, then open the Xcode project:

./deps/build_lame.sh && ./deps/build_ffmpeg.sh
./deps/build_ish.sh && ./deps/prepare_alpine_rootfs.sh
open src/ios/Minis.xcodeproj

For Android, the README states the NDK requirement as r28 or newer. The build prepares the sandbox through a script, then uses the Gradle wrapper in the Android source directory:

./deps/build_proot.sh && ./scripts/prepare_android_sandbox.sh
cd src/android && ./gradlew :app:assembleDebug

The README points to BUILDING.md for the full first-build guide, covering per-platform toolchain requirements, build-time customization templates, and a troubleshooting section for the failure modes most likely to be hit. Expect that troubleshooting section to matter: a chain of four native builds plus a rootfs is not a one-command setup, and the README does not promise it is.

Once the app is running, the first real use is a shell task. Ask the agent to install a package inside the Alpine environment and run a script against a file in a workspace. That exercises the three pieces that distinguish OpenMinis from a chat client: the shell, the workspace addressing, and the model connection you configured with your own credentials. If the shell responds and the file is visible, the sandbox is working.

Where the on-device design costs you

The Linux environment is emulated on iOS through iSH and chrooted on Android through PRoot. Neither is a virtual machine with hardware acceleration. The README's own framing supports reading the sandbox as a compatibility layer rather than a performance one: native offloads exist precisely so that heavy or platform-specific work can be handed to native code instead of the sandbox. If your workload is compiling large projects or processing video inside the shell, you are using the part of the system the maintainers built an escape hatch around.

The second limitation is build complexity, and it is not incidental. Four native dependencies plus a rootfs, with a documented ordering constraint between two of them, means a first build has several places to fail. The README does not document rollback or a prebuilt binary distribution for the native pieces, so recovery from a broken dependency build means cleaning and rebuilding rather than reverting to a known-good artifact.

The third is the platform gap in release cadence. The recent releases listed for the project are Android builds (1.13 and 1.12 on 2026-09-01 and 2026-08-18, plus 0.22-preview on 2026-08-01), while iOS distribution goes through the App Store and TestFlight. The README explains the App Store lag as a review-timing issue, but it does not state that the two platforms are at feature parity, and the release list gives no iOS version numbers to compare against.

Finally, the licence. GPL-3.0 is a strong copyleft licence, and OpenMinis also depends on iSH (GPLv3) and PRoot (GPLv2), with talloc under LGPLv3+. THIRD_PARTY_LICENSES.md holds the full inventory with versions and terms. If you plan to ship a modified OpenMinis inside another product, that is a question for your own counsel, not something the README resolves.

OpenMinis against a server-side agent runtime

The obvious alternative is a hosted agent platform: a cloud sandbox where the agent runs continuously, reachable from any client. The difference is not features, it is where execution and data live. A hosted runtime keeps working when your phone is off, gives you a machine with real CPU and memory, and centralises logs. OpenMinis gives you the opposite trade: execution stays on the device, device APIs are reachable as tools, and there is no server bill for the sandbox itself.

That trade has a clear dividing line. Anything that must run unattended, or that needs more compute than a phone should spend, belongs on a server. Anything that reads your Health data, writes to Reminders, talks to HomeKit or touches Bluetooth belongs on the device, and a hosted agent would need a bridge for each of those. The README's example workflows are all on the device side of that line, which is consistent with the project knowing its own centre of gravity.

The bring-your-own-model layer also changes the comparison. With a hosted platform, inference and orchestration are bundled. With OpenMinis, you supply Claude, GPT or Gemini credentials yourself, so cost, rate limits and data handling are between you and the provider. That is more control and more setup, and the README does not describe any fallback provider or offline model.

Maintenance, releases and licence obligations

The repository is not archived, and the last push was on 2026-09-01, the same day as the 1.13 Android release. The release history shown is recent and regular: 1.13 on 2026-09-01, 1.12 on 2026-08-18, and 0.22-preview on 2026-08-01. On the evidence available, this is a project that ships.

Upgrade cost depends on which path you took. If you use the App Store or TestFlight build, upgrades are the platform's problem, and the README's own advice is that the TestFlight build lands fixes and features first. If you build from source, every upgrade can mean rebuilding the native dependency chain, because those artifacts are not committed. Budget for the dependency build time, not just a git pull.

The licence position is GPL-3.0 for OpenMinis itself, with GPLv3 (iSH), GPLv2 (PRoot) and LGPLv3+ (talloc) in the sandbox stack, and a longer inventory in THIRD_PARTY_LICENSES.md. For individual users this is mostly a non-issue. For anyone embedding the code in a distributed product, the copyleft terms are the first thing to read, and the README does not attempt to summarise them.

Editorial conclusion

Adopt OpenMinis if you want an agent with a real Linux shell and device access on a phone you control, and you are willing to bring your own model credentials and build the native dependencies yourself. Do not adopt it if you need a server-side agent that runs while the phone is asleep, or if GPL-3.0 obligations conflict with how you plan to redistribute the code. Before committing, verify three things: that your target platform's toolchain matches what BUILDING.md requires (NDK r28+ on Android), that your model provider's keys are acceptable to you in a mobile app, and that the skills you depend on actually trigger under Minis' tool system rather than only under the ones they were written for.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. OpenMinis/OpenMinis on GitHub
3. Project website
4. README
5. Releases