ios-linuxkit

ios-linuxkit runs an AArch64 Linux userland inside an iOS app and as a command-line process on an AArch64 Linux host. It derives from iSH and uses iSH's userspace kernel, filesystems and Asbestos threaded-code interpreter.

The current source version is 2.1.0 with Apple build number 806. The repository supports one guest architecture: ARM64. The interpreter decodes guest instructions into programs of pointers to precompiled host functions. All executable host instructions come from the built application; the interpreter allocates only data for translated programs.

• an ARM64 instruction decoder and AArch64 host gadgets under asbestos/guest-arm64/;
• a 48-bit guest address space, Linux syscall layer, signals, sockets and fakefs;
• the iSH-ARM64 iOS application target, Ghostty Web terminal frontend and an iSH-ARM64-ffmpeg integration target;
• Linux-host builds for development and regression testing;
• staged tests for instructions, syscalls, language runtimes and command-line packages.

The iOS app is a reference terminal and packaging target. The outer iOS sandbox is the security boundary; read SECURITY.md before embedding the runtime or exposing guest workloads to untrusted input.

Install Clang, Meson, Ninja, pkg-config, SQLite development files and libarchive development files. On Debian or Ubuntu:

sudo apt install \
  clang make meson ninja-build pkg-config git curl file tar \
  libsqlite3-dev libarchive-dev

Clone the submodules and build:

git clone --recurse-submodules https://github.com/rcarmo/ios-linuxkit.git
cd ios-linuxkit
make build-arm64-linux

Run against the host filesystem:

./build-arm64-linux/ish -r / /bin/echo hello

To create an Alpine fakefs, download the root filesystem named in app/GuestARM64.xcconfig, then import it:

curl -LO https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/aarch64/alpine-minirootfs-3.24.0-aarch64.tar.gz
./build-arm64-linux/tools/fakefsify \
  alpine-minirootfs-3.24.0-aarch64.tar.gz \
  alpine-arm64-fakefs
./build-arm64-linux/ish -f ./alpine-arm64-fakefs /bin/sh

fakefsify is built when Meson finds libarchive. Existing build directories retain their original Meson configuration; remove or reconfigure them when changing the compiler or build type.

The runtime and CLI targets can install packages into their fakefs. Use a disposable copy when package state matters. Reports are written to REPORT_DIR, which defaults to /workspace/tmp.

The July 2026 OpenMinis audit records the repository-wide comparison at 35dac743 and the AdvSIMD conversion follow-up at 40f1bf40. The follow-up added FCVTN, FCVTN2, FCVTXN and FCVTXN2; clean Clang release and debug builds and the native-oracle/guest fixture passed. The earlier broad suite reached 82/83 because the tested rootfs Clojure package lacked clojure.main.

Dated benchmark, workload, release and audit records live under docs/reports/. They preserve their original observations and are not current operating instructions.

ios-linuxkit contains work derived from ish-app/ish and its dependencies. See LICENSE.md, LICENSE.IOS, the preserved May 2026 README, and docs/legacy/.