horus

[!NOTE] Horus 1.1.0 has been submitted to F-Droid and is waiting on their build and review queue. You can wait for it to land there, or build the APK yourself now; see Build from source under For developers below. A self-built APK is signed with your own key, so Android won't install it over the F-Droid or GitHub release; back up anything you need and uninstall that version first.

Claude Code, Codex, and OpenCode in a real Linux terminal on your Android phone.

No root. No Termux. Open source.

Website · Docs · CLI · Issues · Discussions

Horus gives your phone a full Alpine Linux ARM64 workspace and a proper terminal to drive it, then puts the coding agents one tap away. Pick Claude Code, Codex, OpenCode, or a plain zsh shell, point it at a project, and let it work; sessions keep running with the screen off.

For the launch demo, Claude Code downloaded a film, installed ffmpeg, and cut a trailer, while Codex trained a neural network from scratch to 97.97% on MNIST. Both ran on a budget phone from 2021.

𓂻 Install

1. Get the app from F-Droid, or download the APK from GitHub Releases. Both are the same F-Droid-signed file, so you can switch between them and keep your data.
2. Open Horus and set a password. It downloads Alpine Linux (a few MB) and sets up the workspace.
3. Tap an agent. It installs on first open, and you sign in to your account inside the agent itself.

You need an ARM64 phone on Android 7.0 or newer. New to all this? The beginner's guide starts from zero.

𓋹 What you get

𓉐 A real Linux box

Alpine Linux in app storage, checked against a pinned SHA-256 before it's unpacked. git, curl, jq, rg, python3, and Node arrive when you first need them, and apk add gets you the rest.

𓁟 Agents in one tap

Claude Code, Codex, and OpenCode each install into their own home the first time you open them, with the installer output right there in the terminal.

𓏞 A terminal that behaves

Native PTY and renderer with resize, Ctrl‑C, and job control. The key bar adds Esc, Tab, arrows, and sticky Ctrl/Alt for everything a phone keyboard leaves out.

𓊽 Sessions that outlive the app

Terminals run in a foreground service in their own process. Switch apps, lock the phone, let Android kill the UI; the agent keeps going and notifies you when it's waiting on you.

𓊖 Projects and GitHub

Make a folder, clone any HTTPS or SSH URL, or pick from your GitHub repos after a device login in the browser. Everything lives in /workspace/projects, and a read-only file browser previews it and copies folders to Downloads.

𓂀 Private by default

No analytics, ads, crash reporting, or Google services. A password locks the app after 15 minutes in the background, and Horus never touches your agent credentials.

𓊝 Use it from your computer (optional)

Horus works fully on the phone. If you also want to treat it like a small cloud VM, plug it in over USB and use the horus CLI for SSH, file sync, port forwarding, and running one command on a whole drawer of phones:

npm install -g horus-cli
horus pair
horus ssh

The SSH server listens on the phone's loopback only and reaches your computer through adb forward, so nothing is exposed on Wi-Fi. Logins are key-only, root is refused, and pairing needs your Horus password. Settings → Remote access turns it off and lists paired computers you can revoke. The CLI guide covers setup from scratch.

𓇳 How it works

React Native UI (App.tsx, src/)
  │  TerminalRuntime TurboModule + TerminalCanvas / TerminalInput native views
  ▼
Kotlin native layer (android/app/src/main/java/com/scariflabs/horus/terminal)
  ├─ DistroStore*            rootfs download → verify → extract → promote
  ├─ ProotSessionLauncher    builds the PRoot command line and guest environment
  ├─ TerminalSessionService  foreground service in the :terminal process
  └─ NativeTerminalEngine / TerminalCanvasView  VT parsing and rendering
        │
        ▼
terminal_pty.c (JNI) ── PRoot (native/, built from source) ── Alpine rootfs

Each agent runs as its own guest user (UIDs 61001–61003) with a private home, and they all share workspace GID 1000 so they can work on the same projects.

𓅃 Security notes

Android's app sandbox is the only real security boundary. PRoot emulates user IDs but gives no kernel isolation between agent users, so don't run code you don't trust.

Codex's own Linux sandbox doesn't work under PRoot, which is why the shell wraps codex with --sandbox danger-full-access; Codex's approval prompts still apply.

Remote access stays off until you pair a computer or turn it on. Any app on the phone can reach loopback ports, so the paired key is what keeps others out.

𓏛 For developers

You need Node.js ≥ 22.11, JDK 17, and the Android SDK and NDK (the standard React Native environment), plus make, bash, and git for the native runtime.

git clone --recurse-submodules https://github.com/scarif-labs/horus.git
cd horus
npm ci
npm run build:android:debug      # or build:android:release
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

Cloned without --recurse-submodules? Run git submodule update --init to fetch the PRoot and libandroid-shmem sources.

Debug builds embed the JavaScript bundle, so they start without Metro. They also skip the password screens and open straight into a development terminal; release builds have the full onboarding and lock flow.

Release builds stay unsigned unless you pass a keystore through Gradle properties, for example in ~/.gradle/gradle.properties:

horus.releaseStoreFile=/path/to/release.keystore
horus.releaseStorePassword=...
horus.releaseKeyAlias=...
horus.releaseKeyPassword=...

npm run typecheck
npm run lint
npm run test:unit                # Jest (TypeScript / React Native)
npm run test:kotlin              # JVM unit tests for the native layer
npm run test:android:connected   # instrumented tests on a connected device

PRs and pushes to main run Node checks, host native regressions, Android JVM tests, and unsigned release APK validation. See the CI and release maintainer guide for the pinned toolchain, local commands, required checks, and release acceptance.

The diagnostic log stays on the device and records lifecycle metadata only, never terminal input or output.

The build recipe is metadata/com.scariflabs.horus.yml in fdroiddata. New versions are picked up automatically from vX.Y.Z tags.