crate

Compact Runtime for Arm64 Translation and Emulation

Full Linux distributions, desktop and all, running in virtual machines on your iPhone and iPad, entirely on the device.

Ubuntu with GNOME, landscape on an iPhone Duo.

Why crate

  • A real computer in your pocket. Not a remote desktop or a cloud VM: the whole operating system runs on the iPhone, works offline, and your files stay on it.
  • Real distributions. Stock arm64 Linux with its own package manager, so the software you'd run on an Arm laptop or server installs as it is: a browser, developer tools, coding agents like Claude Code, CAD apps.
  • Built for speed. We built crate to be fast, from the engine up. The crate engine is written from scratch in Rust: an arm64-to-arm64 translator that copies most guest instructions into host code as they are and rewrites only what touches the machine. On a Mac, a benchmark pass that takes QEMU's TCG 130.5 s takes crate 24.5 s; the rest of the timings, the iPhone's included, are in the engine's benchmarks.
  • GPU-accelerated. The guest's OpenGL runs on the iPhone's GPU, through virglrenderer, ANGLE and MoltenVK: desktops composite in hardware, and 3D apps render on it.
  • Made for the phone. Touch is a tablet, a key row above the keyboard adds Esc, Ctrl, Super, Tab, function keys and arrows, the desktop follows the phone as it turns or folds, and iPhone Duo gets layouts of its own.

What it runs

Linux comes first. From the Install tab, each with an account of your own:

DistributionDesktop
Ubuntu 26.04 LTSGNOME, the heaviest of them, and it runs
Debian 13KDE Plasma or Xfce
Arch Linux ARMKDE Plasma or Xfce

Coming soon: Omarchy with Hyprland (it runs, with bugs left to fix), custom Linux images of your own, and other operating systems.

Features

  • Ubuntu, Debian and Arch Linux ARM from a catalog, each with an account of your own
  • A disk size of your choice at install, and a memory limit you can change later
  • GPU-accelerated desktops: the guest's OpenGL runs on the iPhone's GPU
  • Touch as a tablet, a hardware keyboard, or the on-screen one with a key row for Esc, Ctrl, Super, Tab, function keys and arrows
  • Supports a mouse or trackpad on iPad: wheel scrolling, right and middle click
  • An external monitor as the VM's screen, at the monitor's resolution, with the iPhone or iPad as its trackpad (GNOME may need its resolution set by hand; see Known issues)
  • iPhone Duo layouts that follow the fold
  • The VM's serial console, a tab away from its desktop
  • JIT from crate's built-in StikJIT, or from StikDebug
  • Logs to share for bug reports, kept across a crash, with memory tracking

Install

crate needs JIT, which iOS gives only to an app a debugger has attached to, so it can't come from the App Store. Each release has an unsigned IPA instead, which you sign with your own Apple account and install from a Mac; JIT is then turned on by crate's built-in StikJIT or by StikDebug (see JIT). INSTALL.md has the steps, and a request to paste into Claude Code, which does them for you. crate is developed on an iPhone Duo with iOS 27.1.

Gallery


Claude Code, running in the VM, builds a chair in SolidCraft, a 3D CAD app, on Ubuntu with GNOME.

Chrome with GPU acceleration: chrome://gpu shows canvas, compositing, WebGL and WebGPU on the iPhone's GPU.

The VM sets its own resolution: 1280 × 800 fits more on screen than the default.

Arch Linux ARM with KDE Plasma, its application menu open.

An external monitor as the VM's screen: Ubuntu fills the monitor, and the iPhone Duo becomes its trackpad.

Roadmap

Speed comes first. Every VM runs on the crate engine, so the engine's speed is the whole app's speed, and that's where help counts most: contributions to the engine go to its repository.

  1. Speed. Faster translation, startup and graphics in the engine, measured by real benchmarks: timings of what people actually do, such as booting to a desktop, opening apps and building code, on the iPhone itself, so every change shows what it gains. Today's numbers are in the engine's benchmarks.
  2. Monitors and devices. An external monitor already works as the VM's screen. Next, the keyboards, mice, game controllers, cameras, microphones, USB storage and other devices iOS lets an app reach, passed through to the VM; the other way, the VM's sound, clipboard and files reaching iOS.
  3. More systems. Omarchy back in the catalog once its bugs are fixed, custom Linux images of your own, then other operating systems.

The app

An iOS app that runs Linux VMs on the crate engine: JIT, installing a VM, and booting it to its desktop. A few UI stand-ins remain (search the code for STUB, SAMPLE DATA and PLACEHOLDER).

Three tabs:

  • Home: the installed VMs, one large card each, with the screen each was showing when last stopped (preview.jpg in its folder) and Start. A card's menu has the VM's settings (on iPhone Duo) and Delete.
  • Install Vms: the images the catalog lists, a memory limit, and Install, which asks for the account to make in the VM.
  • Settings: JIT, memory, logs, and Acknowledgements: the licenses of crate and of everything it carries.

JIT

crate claims its code region at launch, or once a debugger arrives: mapped executable, authorized by the debugger on brk #0x69 (StikDebug's legacy.js convention), then mapped again for writing, and test-run. Two ways to get the debugger, picked in Settings:

  • StikDebug: crate opens stikdebug://enable-jit with its pid and legacy.js; StikDebug attaches and comes back.
  • Built-in StikJIT: a helper extension (Sources/JITHelper) runs StikJIT (MPL-2.0) through LocalDevVPN's tunnel. Set Up JIT pairs the iPhone with crate itself on iOS 27 (or takes a pairing file), with idevice (MIT), built from source with one patch (Scripts/patches).

Each launch logs its JIT steps to Library/Caches/crate.log, and pairing's messages to Library/Caches/idevice.log.

The engine

crate runs the VM in this process, on the code region JIT claimed. The VM screen switches between its display (a virtio GPU, frames handed straight to the app, touch and keys as a virtio tablet and keyboard) and its serial console in a terminal (SwiftTerm, MIT). On an iPhone the GPU does 3D: the guest's OpenGL runs on the iPhone's GPU through virglrenderer, ANGLE and MoltenVK, each built from upstream source (see docs/PROVENANCE.md); in the Simulator the guest draws in software. The network is user-mode, through libslirp (BSD-3-Clause) and GLib (LGPL-2.1-or-later), built from source as dynamic frameworks the app embeds.

VM images

The images come from arm64-desktop-images, whose GitHub workflow builds and attests them: Ubuntu with GNOME, Debian with KDE Plasma or Xfce, and Arch Linux ARM with KDE Plasma or Xfce. Each release has a catalog.json listing every image's kernel, initrd and disk (xz, in parts under 2 GiB) with their SHA-256s, its kernel command line, and its cloud-init vendor-data.

Install reads the latest catalog, downloads an image (crate must stay open meanwhile), checks every file, unpacks the disk through Apple's xz decoder as its parts arrive (sparsely: empty space takes no room) and grows it to 32 GB. The account comes from a seed disk crate writes beside it (seed.img, FAT, labelled CIDATA): cloud-init's NoCloud user-data with the user, a SHA-512 crypt of the password, the hostname and time zone, plus the image's vendor-data (its desktop's autologin). The seed stays attached read-only, so cloud-init sets the VM up once. A VM's files are in Library/Application Support/VMs/<its ID>/.

A VM can still be put on the iPhone by hand: copy vmlinuz, initrd.img and disk.img into its folder with devicectl device copy to ... --user mobile (without it crate can't write to the disk; never add --remove-existing-content, which empties the app's whole container). It boots with aTerm's command line.

Debug builds can be driven from a Mac the same way: while a VM runs, an empty Library/Caches/debug/screen gets its display saved as screen.png there, debug/command.txt is typed into its console, and debug/size.txt ("WxH" in points) resizes its desktop as rotating or folding the iPhone would. Launched with CRATE_GL_DEBUG=1 (devicectl device process launch -e), crate logs ANGLE's own GL messages; with CRATE_LOG=debug, its debug lines.

Build

The libraries go into Frameworks/, which isn't committed. Fetch them, each pinned to a release and checked against its SHA-256:

./Scripts/fetch-frameworks.sh  # idevice, libslirp and GLib, the GPU stack
./Scripts/fetch-stikjit.sh     # StikJIT 2.0.1
./Scripts/fetch-crate.sh       # crate v0.1.1
xcodegen generate
open Crate.xcodeproj

or for the Simulator:

xcodebuild -project Crate.xcodeproj -scheme Crate \
    -destination 'generic/platform=iOS Simulator' -derivedDataPath build build

Launch arguments show one state without tapping to it:

xcrun simctl launch booted com.amendez.crate --tab=install --jit=on
# --tab=home|install|settings  --jit=on|off  --empty  --samples
# --rail: the open Duo's tab column, on any device

With --jit=on the Simulator has no code region, so starting a VM pretends: its screenshot becomes the display, and the console shows a login prompt that echoes typing.

VERIFY_ATTESTATION=1 makes the crate and frameworks fetches also check, with gh, that each release's own workflow built it. To change crate and the app at once, build crate from a checkout instead of fetching it:

./Scripts/build-crate.sh       # crate from ~/Repos/crate (CRATE_DIR); needs Rust

The frameworks release is these scripts' output; build them to change one, and publish a new release with ./Scripts/release-frameworks.sh TAG, then pin the VERSION and SHA256 it prints in fetch-frameworks.sh:

./Scripts/build-idevice.sh     # idevice v0.1.68 from source; needs Rust
./Scripts/build-slirp.sh       # libslirp 4.9.7 and GLib 2.90.1; needs meson
./Scripts/build-moltenvk.sh    # MoltenVK 1.4.2; about 15 minutes
./Scripts/build-angle.sh       # ANGLE; a 4 GB checkout, ANGLE_SRC reuses one
./Scripts/build-virgl.sh       # libepoxy 1.5.10 and virglrenderer 1.3.0; needs PyYAML

Once this repository is public, the frameworks workflow, run by hand, does the same on GitHub: it builds them all, publishes the release with an attestation, and shows the lines to pin. While the repository is private it skips itself.

IPA

The ipa workflow builds an unsigned IPA from the same pinned libraries: run by hand it's a workflow artifact, and a version tag (vX.Y) makes it a release. ./Scripts/build-ipa.sh builds the same IPA on a Mac. Scripts/sign-ipa.sh signs it with your own certificate and profiles under your bundle ID, as INSTALL.md describes, and can install it:

BUNDLE_ID=com.you.crate ./Scripts/sign-ipa.sh crate-unsigned.ipa                # crate-signed.ipa beside it
BUNDLE_ID=com.you.crate ./Scripts/sign-ipa.sh crate-unsigned.ipa --install UDID

Both bundles get get-task-allow, which turning JIT on needs, and the app the two memory entitlements when its profile grants them. Unset, BUNDLE_ID is this project's own, com.amendez.crate.

Known issues

  • A guest can't update its own kernel. crate boots a VM's kernel and initrd from outside its disk, so the images hold their kernel packages at the version they shipped with. A kernel the guest installs anyway is never booted, and an upgrade can remove the modules the booted kernel needs.
  • Xfce's wallpaper doesn't follow a new screen size. When the desktop changes size, on an external monitor for one, Xfce's panel, icons and windows follow it, but the wallpaper keeps its old size.
  • GNOME may not resize to fit a monitor. If Ubuntu's desktop doesn't fill an external monitor, open Settings → Displays inside the VM and pick a resolution with the monitor's aspect ratio, such as 1920 × 1080 for a 16:9 monitor.

License

crate's own code is MPL-2.0, like the crate engine: changes to crate's files stay open, and it can be combined with code under other licenses. What the app carries from other projects keeps its own license: StikJIT (MPL-2.0), idevice and SwiftTerm (MIT), libslirp (BSD-3-Clause), GLib (LGPL-2.1-or-later, kept as its own replaceable framework), MoltenVK (Apache-2.0), ANGLE (BSD-3-Clause), libepoxy and virglrenderer (MIT), and what they in turn are built from. docs/PROVENANCE.md says where each comes from and how it's built, and THIRD_PARTY_NOTICES.md has every license's text (Scripts/third-party-notices.py writes it). JIT is turned on with StikDebug's convention, and the VM images are each distribution's own, under their licenses.