Local Desktop

Local Desktop helps you run a desktop Linux environment on your Android device.

Note: It is expected that you already have a usable desktop experience, i.e., a large enough display (tablet or DEX), a physical keyboard, and optionally a mouse/trackpad. Local Desktop aims to bridge the gap between the two platforms, not trying to "simulate" the desktop experience by introducing inconvenient interactions.

How it works

1. An Arch Linux ARM64 filesystem is set up inside the app's internal storage.
2. Proot mounts the filesystem and provides a chroot-like environment.
3. A minimal built-in Wayland compositor runs in Android NDK.
4. An Xfce Wayland session launches inside the chroot and renders back to the Android native activity.

Proof of Concept: A Pixel Tablet running the XFCE desktop environment inside a Proot-based ARM64 Linux. No configuration is required; just install and go.

Getting Started

How to build an APK

Termux

You can build the Local Desktop APK directly on your Android device. This is simple because no cross-compilation is needed. However, we only ship prebuilt libs for arm64, so this option only works on ARM64.

For Termux, there are two supported approaches:

1. Simple build (no xbuild)

   Install Rust:

   pkg i rust
   

   Then run:

   cargo run

   This uses the built-in Rust APK builder and writes localdesktop.apk in the project root.

2. xbuild-based build

   This matches the desktop cross-build pipeline more closely and is better for repeated APK builds:

   bash scripts/build-termux.sh

   This script installs the required Termux packages, bootstraps the patched xbuild toolchain, downloads the Android SDK build-tools, and writes the APK to target/x/release/android/localdesktop.apk.

For the simple cargo run flow, you can install the APK with termux-open localdesktop.apk, but in some cases you may need to mv localdesktop.apk ~/storage/downloads and install it from there. Make sure you have run termux-setup-storage before moving it outside Termux.

Linux/Mac/Windows

The above option is suitable for quick development on Android. However, if you need to build an AAB (for distribution to Google Play), debug with Visual Studio Code, or compile for unsupported targets (like x64 Android), then you need to cross-build it from your PC. Along with Rust, please make sure you have these components installed:

brew install llvm lld gradle@8

Then install our local version of xbuild:

cargo install --path patches/xbuild/xbuild --force
x build --release --platform android --arch arm64 --format apk

Alternatively, trigger the default build task by pressing Ctrl+Shift+B.

You can find the output APK in:

open target/x/release/android/gradle/app/build/outputs/apk/debug/app-debug.apk

Docker

If you have issues setting up your local development environment as detailed above, you can make use of the included Dockerfile to build an APK on a single command. This will take a long time so it's not recommended if you can make use of any of the other methods

make build-docker

You can find the output APK in:

open target/x/release/android/localdesktop.apk

How to develop

Termux

We recommend the following setup, but feel free to use your own favorite tools for development:

pkg install helix helix-grammars rust-analyzer

A wonderful thing about developing directly on Android is that an agent like Codex on Termux can test the code for you by running unit tests, reading the output, understanding what went wrong, and trying again. In my experience, this is not possible when cross-developing on other operating systems, so you have to run the tests yourself.

Linux/Mac/Windows

Recommended setup:

• IDE: Visual Studio Code

• Extensions:

  • Rust Analyzer
  • Android Debug
  • CodeLLDB

• Instructions:

  1. Open Visual Studio Code.
  2. Launch the [Android] Debug configuration from the debug panel. This will:
     • Build the Rust code into an APK.
     • Install the APK on a selectable device, and launch the app in debug mode.
     • Redirect stdout/stderr output to the terminal.

Tip: You can debug the app on either a physical device or a virtual device.

For more instructions on how to work on this project, please visit the Developer Manual.

Offline documentation

The build_docs binary builds offline-readable PDFs into manuals/ (gitignored). It's all Rust — Typst renders the PDF as a library and the image crate handles screenshots, so there's no pandoc, LaTeX, or Python to install. It produces two manuals, selected by the first word:

cargo run --bin build_docs                 # Developer Manual (default)
cargo run --bin build_docs -- user         # User Manual
cargo run --bin build_docs -- all          # purge manuals/ + rebuild every variant

• Developer Manual — everything: this README, the full gh-pages user + developer guides and blog, and an architecture walkthrough of the code. Book-like (Cardo serif). → manuals/Local Desktop - Developer Manual.pdf
• User Manual — the gh-pages user guide and blog, with screenshots, styled to feel like the website (Lato sans, teal accents). → manuals/Local Desktop - User Manual.pdf

Extra knobs (words, in any order):

• Page size — desktop (default, A4), fold (near-square 130×150mm, for a foldable's inner screen), or phone (narrow/tall ~90×190mm, for a normal mobile phone).
• dark — User Manual only: the website's dark "northern lights" theme (dark page, light text, bright-teal accents, dark code blocks).
• callgraph — Developer Manual only: replace the hand-written architecture walkthrough with one generated by actually walking the call graph from the seed functions. See the two architecture modes below.

cargo run --bin build_docs -- callgraph fold      # developer, call-graph, fold page
cargo run --bin build_docs -- user dark           # user manual, dark theme
cargo run --bin build_docs -- user phone dark     # user manual, dark, phone page

all regenerates the full set, so manuals/ only ever holds the latest build: Local Desktop - {Developer,User} Manual [(Call Graph|Fold|Phone[, Dark])].pdf.

The User Manual ships as release artifacts in 6 variants — every size (desktop/fold/phone) × theme (light/dark) — attached alongside the APK/AAB as Local-Desktop-v<version>-User-Manual[-Fold|-Phone][-Dark].pdf. The app also pre-downloads the matching desktop/light manual onto the Linux desktop during setup.

The Developer Manual's architecture part comes in two modes:

• curated (default) — a hand-written walkthrough (docs/architecture.md) that flattens the program along its call stack: android_main → the WebView and Wayland backends → the xbuild and build_apk build paths. Readable and story-shaped; the code in each snippet is pulled fresh from source on every build, so it can't drift.
• callgraph — generated by actually walking the call graph from the seed functions (see CALLGRAPH_SEEDS in src/bin/build_docs/). Exhaustive but mechanical; being lexical and intra-crate, it can't see trait/dyn dispatch and resolves same-name methods heuristically.

The tool is host-only (#[cfg(not(target_os = "android"))] deps), so it never affects the Android app build.