Architecture

A public technical model of ternux. This explains the boundaries and failure modes without publishing the private Pro deployment implementation.

The stack

┌─────────────────────────────────────────────────────┐
│ Android                                             │
│                                                     │
│  Termux:X11 app ◀──── X11 display ────┐             │
│                                       │             │
│  Termux host                          │             │
│  ├─ display and audio services        │             │
│  ├─ PRoot supervisor                  │             │
│  └─ optional VirGL service            │             │
│               │                       │             │
│               └─ PRoot Debian ────────┘             │
│                  ├─ Xfce4 desktop                   │
│                  ├─ Debian applications             │
│                  └─ Mesa / Zink / VirGL             │
│                                                     │
│  Adreno kernel GPU interface ◀── Turnip path        │
└─────────────────────────────────────────────────────┘

Android

Android owns the kernel, hardware drivers, application sandbox, power policy and process limits. ternux does not replace Android, unlock the bootloader or obtain root. That makes deployment safer, but it also means PRoot cannot grant hardware capabilities Android does not expose.

Termux

Termux is the host-side Linux environment. It coordinates the PRoot container and the services that must live outside it. Closing or suspending Termux can therefore end the desktop session even while Termux:X11 remains visible.

PRoot Debian

PRoot provides a Debian userland without a privileged chroot. It rewrites paths and selected system calls in userspace. Most normal arm64 Debian applications work, but systemd, kernel modules, privileged mounts and direct hardware control are not equivalent to a native Debian machine.

Termux:X11

Termux:X11 is the Android display application. It renders the X11 session; it is not itself the Debian desktop. A black or empty Termux:X11 view can mean the app is healthy while the host service, socket or Xfce4 session is not.

Graphics routes

Zink + Turnip on supported Adreno devices

OpenGL application
       │
       ▼
     Zink          OpenGL → Vulkan translation
       │
       ▼
 Vulkan loader
       │
       ▼
    Turnip         Mesa Vulkan driver for Adreno
       │
       ▼
 Android / kernel GPU interface

This is the preferred route. It gives OpenGL applications a hardware-backed Vulkan path without requiring an Android-native build of each desktop app. Driver, loader and device visibility must all agree; one missing layer can leave a desktop that still opens but renders on the CPU.

VirGL on other GPUs

OpenGL application
       │
       ▼
 virpipe / VirGL
       │
       ▼
 host-side VirGL service
       │
       ▼
 Android graphics stack

VirGL is the compatibility route for Mali, Xclipse, PowerVR and other hardware where Turnip is not applicable. It is expected to be slower. Selecting VirGL is not a failed Adreno setup; pretending non-Adreno hardware can use Turnip would be the failure.

Audio and file boundaries

Audio crosses the PRoot boundary through a loopback-only bridge between Debian applications and a Termux-side audio service. Loopback binding is important: a mobile workstation should not expose an unauthenticated audio or model service to the local network by default.

Debian home, Termux home and Android shared storage are distinct locations. Shared storage is the hand-off point for Android apps, while Git or remote storage should protect source code and irreplaceable projects.

Verified deployment phases

The private Pro implementation is organised around nine acceptance boundaries:

Device and application preflight
Host-side Termux foundation
Debian/Xfce4 workspace
GPU-route selection
Display, audio, locale and storage integration
Reliable launch, stop and recovery controls
Android background-process safeguards
Renderer and service acceptance tests
Report, workload selection, baseline and backup handover

This sequence is public because it explains what is being verified. The exact commands, installer modules, private endpoints, rollback code and version-bound operator runbook are Pro release materials.

State, resume and recovery

Mobile networks drop, Android reclaims processes and multi-gigabyte downloads are interrupted. A professional deployment must treat interruption as an expected state, not an edge case.

Idempotency: a completed phase can be checked or re-entered without duplicating configuration.
Recorded resume: the private alpha records completed modules and can skip them on a later run.
Targeted repair: doctor checks map a failure to the responsible module.
Verification before progression: core static checks exist; the explicit live-session acceptance command still needs real-device Zink/VirGL validation.
Transactional rollback: this is a release blocker, not a current feature. The alpha does not yet reverse every partial module change.
Supportable output: every failure should name the check, expected result, observed result and safe next action.

Silent failure modes

Failure	Why the desktop may still open	Acceptance evidence
Vulkan loader/driver path incomplete	Mesa can fall back to CPU rendering	Renderer must not say `llvmpipe`
Graphics components replaced by an update	Stock Mesa still renders a desktop	Compare renderer and toolkit report with the known-good baseline
Wrong backend selected	A compatible but slower route may still function	GPU evidence and selected route must agree
Host-side VirGL service missing	Software fallback can hide the missing service	VirGL service and renderer checks must both pass
Android process policy intervenes	The session initially works, then loses processes	Long-enough stability check and Android policy report

A visible Xfce4 desktop is therefore not the definition of success. The renderer string, service health and a clean second launch are stronger evidence.

Workload consequences

Blender: viewport usefulness depends on the graphics route, scene complexity, memory and thermals. A smooth low-poly scene does not predict a large render or simulation.
Local AI: Vulkan offload shares the same physical memory and thermal budget as Android and the desktop.
Development agents: tool execution occurs inside the user’s environment; provider credentials and command approval remain security boundaries.
Security tools: PRoot provides Debian userspace, not unrestricted wireless monitor mode, USB access or arbitrary kernel capabilities.
Sustained compute/mining: long constant load is especially exposed to throttling, battery drain and wear, so it is not a recommended target.

Public and private boundary

Public documentation should let a careful reader understand compatibility, architecture, daily operation, evidence of success and realistic limitations. It should not contain licence secrets, live private endpoints, proprietary installer modules or the complete version-bound deployment recipe.

An obscure path, noindex tag or Jekyll exclusion does not make source private inside a public repository. Private Pro documentation belongs in an access-controlled repository and protected delivery channel.