Miauterm

An experimental Android terminal that runs Debian ARM64 in PRoot.

Project status: Experimental
The published APK is a test release for ARM64 Android devices. Runtime behavior and package compatibility can vary by device and Android version.

Miauterm is an unofficial, experimental fork of Cortex Terminal. It retains upstream terminal and Android application code while replacing Cortex's native Ubuntu runtime with a Debian 13 (Trixie) ARM64 root filesystem launched through PRoot. Miauterm is an independent project and is not affiliated with or endorsed by the Cortex maintainers.

Why PRoot

Cortex Terminal runs Ubuntu natively on Android using its own userspace integration. Its upstream README describes that design as running without PRoot, a virtual machine, CPU emulation, or Android root access.

Miauterm uses PRoot to run Debian userspace on Android. A conventional Linux distribution expects its own user and group databases, filesystem layout, permissions, and package tools. Android's app environment does not provide those pieces as a standard distribution root filesystem.

PRoot lets Miauterm use Debian's own root filesystem, including /etc/passwd, the group database, and apt, without requiring root access to Android. Miauterm does not emulate an ARM CPU; the bundled Debian system and its native programs target arm64-v8a devices.

	Cortex Terminal	Miauterm
Linux userspace	Ubuntu 24.04, as described by upstream	Debian 13 (Trixie) ARM64
Runtime	Native Android userspace integration	PRoot
CPU emulation	None	None for the ARM64 build
Android root required	No	No
Android security boundary	Android application sandbox	Android application sandbox

Compatibility trade-offs

PRoot does not boot a second Linux kernel. It uses ptrace to present a guest filesystem and translate guest process requests to the Android host kernel. This model brings the following compatibility limits; see the PRoot overview and PRoot manual.

• Some workloads run slower. PRoot adds work while tracing processes and translating filesystem and system calls. Package installation, compilation, and commands that perform many small file operations can take longer than they would on a native Linux system. The impact depends on the command and device.
• Privileged operations can fail. PRoot can simulate some filesystem behavior for compatibility, but it cannot load kernel modules or mount filesystems that require real kernel privileges.
• The Android kernel sets the limits. Debian programs use the Android host kernel, not a Debian kernel. Software that depends on a particular kernel feature, device, mount, namespace, or cgroup may not work. A full machine boot with systemd and kernel-managed services is outside Miauterm's runtime model.
• Architecture support is limited to ARM64. Miauterm bundles an ARM64 Debian rootfs and does not configure QEMU user-mode emulation for foreign binaries. Installing x86 or x86-64 packages therefore does not make their binaries runnable in this build.
• Tracing and nested runtimes can be restricted. PRoot itself uses ptrace, so debuggers, profilers, nested PRoot environments, and container tools that need their own tracing or kernel features may have limitations.
• Networking belongs to the Android app. Debian uses the app's network connection rather than a separate virtual network interface. Android VPN, DNS, firewall, and background restrictions can affect package downloads and other network commands.
• Linux users are not separate Android users. Debian's root and regular users share Miauterm's Android app identity and private storage boundary. Creating a Debian user does not create a separate Android security identity.

Package compatibility depends on the program's kernel requirements, architecture, and behavior under PRoot. A package installing successfully does not guarantee that every feature it provides will work on every Android device. This trade-off is intentional: Miauterm prioritizes Debian compatibility over native execution.

Features

• Bundled Debian 13 ARM64 root filesystem with first-run extraction progress.
• PRoot terminal sessions, a failsafe shell, and Debian reset, backup, and restore tools.
• File browser for the app's Linux files, with file type and write-permission indicators.
• Optional access to Android's Download and Documents folders. Access is off until enabled by the user.
• Terminal themes, font selection, custom font reload, and configurable extra keys.
• User selection for Debian sessions. An empty selection starts a root PRoot session; configured users are selected by their exact Debian username.
• PRoot diagnostics and optional logging controls in Settings.
• miauterm-cmd for commands that connect a Debian shell to selected Miauterm app functions.

These features are implemented across Miauterm changes and retained Cortex components. See Credits and THIRD_PARTY_NOTICES.md for attribution and component notices.

Requirements and storage

Requirement	Details
Android version	Android 7.0 (API 24) or newer
Target SDK	28
CPU architecture	arm64-v8a
Linux distribution	Bundled Debian 13 (Trixie) ARM64 root filesystem
App version	0.1.1

Miauterm stores Debian inside its app-private files directory and extracts the bundled root filesystem on first start. Leave enough device storage for the extracted system and any packages you install. apt update and package installation require network access.

If enabled in Settings, only the selected Download and Documents locations are shared with new Linux sessions under ~/android/. Miauterm does not give Debian general access to Android storage.

Download

Download the signed ARM64 APK from the Miauterm v0.1.1 release:

• Installable release APK
• Release APK SHA-256
• Debug APK

The Releases page contains the current APKs and their checksums. The Build APK workflow runs rootfs validation and selected tests, builds ARM64 APKs, and verifies the release package before publishing it.

Terminal commands and fonts

Show the available app commands from a Debian shell:

miauterm-cmd --help

For a custom font, place a readable TTF file at ~/.config/miauterm/font.ttf in the selected Debian user's home, select Custom Font in Settings, then run this in the active terminal:

miauterm-cmd run reloadfont

The app command service must be active for miauterm-cmd commands to reach Android. The command list and arguments are also documented in the bundled miauterm-cmd script.

Build from source

The GitHub Actions workflow is the project's release build path. It uses Java 17, Gradle 8.7, Android SDK platform 35, NDK 26.1.10909125, and CMake 3.22.1.

On a development computer with those tools installed, build a debug APK with:

./gradlew :app:assembleDebug

The APK is written under app/build/outputs/apk/debug/. The release variant requires the signing environment variables configured in app/build.gradle.kts; do not commit signing keys or passwords.

To inspect CI build results, open Actions. The workflow also validates the bundled Debian root filesystem before building.

Project structure

miauterm/
├── .github/
│   ├── dependabot.yml
│   ├── release-notes/
│   │   └── v0.1.1.md
│   └── workflows/
│       └── build-apk.yml
├── app/
│   ├── build.gradle.kts
│   ├── proguard-rules.pro
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml
│       │   ├── assets/
│       │   │   ├── debian-arm64.tar.zst
│       │   │   ├── fonts/
│       │   │   ├── licenses/
│       │   │   ├── miauterm-cmd
│       │   │   └── proot/arm64-v8a/
│       │   ├── java/org/cortex/terminal/
│       │   │   ├── api/       # Android app command bridge
│       │   │   ├── runtime/   # Debian, PRoot, backup, and file operations
│       │   │   ├── service/   # Background terminal service
│       │   │   ├── session/   # Terminal session lifecycle
│       │   │   └── view/      # Terminal and extra-key views
│       │   └── res/
│       │       ├── drawable*/
│       │       ├── layout/
│       │       ├── mipmap*/
│       │       ├── values*/  # Strings and localized Android resources
│       │       └── xml/
│       └── test/java/org/cortex/terminal/
│           ├── api/
│           ├── runtime/
│           ├── service/
│           ├── session/
│           └── view/
├── core/
│   └── terminal-engine/
│       ├── build.gradle.kts
│       └── src/
│           ├── main/cpp/     # PTY bridge, CMake config, and Zstandard sources
│           ├── main/java/org/cortex/terminal/
│           │   ├── emulator/
│           │   ├── pty/
│           │   └── view/
│           └── test/java/org/cortex/terminal/emulator/
├── docs/
│   ├── images/
│   └── SECURITY.md
├── gradle/
│   ├── libs.versions.toml
│   └── wrapper/
├── scripts/
│   ├── package-debian-rootfs.sh
│   ├── sanitize-rootfs-tar.py
│   └── verify-rootfs.sh
├── build.gradle.kts
├── gradle.properties
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
├── LICENSE
├── README.md
└── THIRD_PARTY_NOTICES.md

The org.cortex.terminal package and core/terminal-engine contain upstream-derived code alongside Miauterm changes. The package names do not imply that Miauterm authored the retained upstream components.

Credits

• Cortex Terminal for the upstream Android terminal application and terminal engine code used as the starting point for this fork.
• PRoot for the user-space runtime used to launch Debian.
• Debian for Debian 13 and its ARM64 userspace.
• JetBrains Mono and Fira Code for bundled fonts.

See THIRD_PARTY_NOTICES.md and the files under app/src/main/assets/licenses/ for the notices supplied with bundled components.