Kakehashi: Running macOS ARM64 Binaries on Linux aarch64

Kakehashi is an experimental userspace translation layer designed to execute macOS ARM64 binaries on Linux aarch64 hosts. By mapping Darwin Mach-O binaries and translating BSD syscalls to Linux, Kakehashi enables the execution of real macOS CLI guests—such as curl and 7-Zip—on bare-metal Linux, VMs, or within Docker containers.

Core Architecture and Implementation

Kakehashi operates as a translation layer rather than an instruction emulator, meaning guest code runs natively on the CPU. The performance overhead is concentrated at the syscall boundary, where the system performs TLS switches, alternative stack management, and NEON save/restore operations.

Technical Components

The project is organized into several Rust crates:

  • kakehashi: The primary CLI tool (kh) used to manage and run binaries.
  • kh-loader: Handles the parsing, mapping, and execution of Mach-O binaries.
  • kh-runtime: Manages memory, traps, and BSD syscall translation. It embeds a freestanding libSystem.B.dylib to provide essential system libraries to the guest.
  • kh-libsystem: The source for the embedded dylib (compiled specifically for aarch64-apple-darwin).

The "Bottle" System

Kakehashi uses a "bottle" layout to simulate a macOS environment. The default root is located at ~/.local/share/kakehashi/bottle/. This layout bridges the host filesystem to the guest, allowing paths like /Volumes/linux/ in the guest to map directly to the host's root filesystem.

Current Capabilities and Verified Tools

Kakehashi is currently a CLI-first project and does not support GUIs, codesigning, or the full Apple Security.framework. However, several high-profile CLI tools have been verified:

  • 7-Zip (7zz): Supports multi-threaded compression (-mmt=4) and has been verified on 8k-file trees.
  • curl: Over 200 commands and options have been successfully tested, including HTTPS GET requests using a seeded CA bundle.
  • Xcode Tools Git: Basic version control commands such as init, add, and commit are functional, though the author notes that 100% stability is not yet guaranteed.

Performance and CI/CD Use Case

While Kakehashi does not match native macOS performance, it is designed to be a viable alternative for CI/CD pipelines where cost and availability are the primary drivers.

Performance Benchmarks

In tests on Ubuntu aarch64 bare-metal (UTM) using a multi-file 7zz archive (~240 MiB tree), the performance gap was measured as follows:

Implementation Wall Time Ratio
Native Linux 7zz ~22.5 s 1.0x
Darwin 7zz under kh ~118 s ~5.2x

For compression-heavy tasks with few files, the gap narrows to approximately 1.1x–1.2x. The ~5.2x slowdown in multi-file scenarios is attributed to the overhead of path walking and the per-syscall boundary, not the efficiency of the compression algorithm itself.

Economic Value in CI

The project's goal is to enable the use of cheap Linux aarch64 runners instead of expensive macOS runners. For example, GitHub Actions hosted runners for Linux 2-core arm64 cost approximately $0.005 per minute, while macOS 3–4 core runners cost approximately $0.062 per minute. Even with a 5x performance penalty, the billable cost of running a job on Linux via Kakehashi can be significantly lower than using a native macOS runner.

Installation and Requirements

System Requirements

  • Host OS: Linux aarch64 (required for kh run and kh trace).
  • Rust Version: 1.88+.
  • Page Sizes: Supports both 4 KiB (containers) and 16 KiB (Asahi-class).

Quick Start

Users can install the tool via Cargo:

cargo install kakehashi
kh bottle ensure
kh install 7zip
kh install curl

Community Insights and Context

Discussion among users highlights the project's positioning relative to other efforts like Darling. The author explicitly states that Kakehashi is not derived from Darling and is a clean-room implementation.

Community members have expressed interest in potential future expansions, such as running Audio Unit (AU) binaries on Linux, and the ability to build iOS apps on Linux ARM runners. Some users have questioned the project's use of AI in generating documentation, while others have noted the similarity to inverse projects attempting to run Linux binaries on macOS using Zig.

Sources