hl core only. AppKit X and runnable applications live in public sibling repositories:

The pre-split monorepo is preserved by tag split-base-2026-07-30.

hl executes aarch64-linux and x86_64-linux ELF binaries on macOS Apple Silicon using Apple's Hypervisor.framework. No Docker, no full VM — just a lightweight per-process virtual machine that translates Linux syscalls to macOS equivalents.

$ hl ./hello-linux
Hello from Linux!

• 172 Linux syscalls translated to macOS equivalents
• Static and dynamic ELF binaries — use --sysroot for dynamically-linked programs
• x86_64-linux via Rosetta — transparent JIT/AOT translation for x86_64 ELF binaries
• Multi-threading — guest threads map 1:1 to host pthreads, each with its own HVF vCPU
• fork/clone — implemented via posix_spawn + IPC state serialization
• execve — full ELF reload with interpreter, page table rebuild, vCPU restart
• Signal delivery — rt_sigaction, rt_sigreturn, SIGPIPE, ITIMER_REAL
• Socket networking — AF_INET/AF_INET6 with sockaddr/sockopt translation
• inotify — emulated via kqueue EVFILT_VNODE
• /proc emulation — /proc/self/exe, /proc/self/maps, /proc/self/stat, /proc/self/fd/
• Rooted VFS — --fs-mode=rooted with bind mounts, virtual CWD, reverse host→guest map
• OSS audio — /dev/dsp + /dev/mixer bridged to Core Audio (null/WAV backends for CI)
• 2MB + 4KB page tables — automatic L3 splitting for mixed-permission regions (W^X)
• Demand-paged memory — up to 1TB address space, only used pages consume RAM

By default hl runs with a product-oriented profile:

• --fs-mode=rooted
• bind $HOME → /home/user
• --guest-cwd /home/user
• --audio-backend coreaudio

# Same as the defaults (home media + Core Audio)
hl ./my-linux-app

# Hermetic / no auto home bind
hl --isolated --bind /path/to/media:/media ./app

# Deterministic tests (legacy paths + silent backend)
hl --fs-mode=legacy --audio-backend null ./test-program

# Category traces: HL_TRACE=fs,fd,dev,audio,proc,fork,sys

• macOS on Apple Silicon (M1/M2/M3/M4)
• macOS 13+ (macOS 15+ recommended for 40-bit IPA / 1TB address space)
• Hypervisor.framework entitlement (com.apple.security.hypervisor)

curl -fsSL https://hyper-linux.app/install.sh | sh

Downloads, verifies SHA256, codesigns, and installs to /usr/local/bin.

brew install zw3rk/hyper-linux/hl

Download the latest .pkg or .zip from Releases:

# macOS installer package
sudo installer -pkg hl-v0.2.4.pkg -target /

# or unzip manually
unzip hl-v0.2.4.zip -d /usr/local/bin/

nix run github:zw3rk/hyper-linux

Or add to your flake inputs:

{
  inputs.hyper-linux.url = "github:zw3rk/hyper-linux";
}

Requires the nix development shell (provides cross-toolchain, SDK, signing):

git clone https://github.com/zw3rk/hyper-linux.git
cd hyper-linux
nix develop -c make hl

The built binary is at _build/hl, codesigned with the Hypervisor entitlement.

hl [options] <elf-binary> [args...]

# Static aarch64-linux binary
hl ./my-static-binary arg1 arg2

# Dynamically-linked binary with musl sysroot
hl --sysroot /path/to/musl-sysroot ./my-dynamic-binary

# x86_64-linux binary (uses Rosetta for translation)
hl ./my-x86_64-binary

# Verbose output for debugging
hl -v ./program 2>debug.log

# GNU coreutils (static musl build)
hl /path/to/coreutils/bin/ls -la

1. hl creates a lightweight HVF virtual machine with a minimal EL1 shim
2. The ELF binary is loaded into guest memory with identity-mapped page tables
3. The shim provides exception vectors that forward Linux syscalls (SVC #0) to the host via HVC #5
4. The host translates each syscall to its macOS equivalent (errno values, flags, struct layouts)
5. For x86_64 binaries, Apple's Rosetta translates instructions to ARM64 at runtime

Guest memory is demand-paged — the VM address space can be up to 1TB but only touched pages consume physical RAM.

# Enter development shell
nix develop

# Build
make hl

# Run tests
make test-both-modes       # aarch64 suite in legacy + rooted modes
make test-x64-both-modes   # x86_64/Rosetta suite in both modes
make test-host-units       # Host units + operator diagnostics
make test-coreutils        # 104 GNU coreutils tools
make test-busybox          # BusyBox applets
make test-static-bins      # Static binaries (bash, lua, jq, etc.)
make test-dynamic          # Dynamically-linked binaries
make test-dynamic-coreutils # Dynamic coreutils with sysroot
make test-haskell          # GHC-compiled Haskell binary
make test-x64-hello        # x86_64 via Rosetta

# All available targets
make help

Release maintainers: see docs/RELEASING.md.

All source lives under src/ (~26,000 lines of C + assembly):

• No full kernel environment — no namespaces or cgroups; /dev is a targeted virtual registry including null/zero/random and OSS audio nodes
• Single-VM fork — macOS HVF allows one VM per process; fork uses posix_spawn + IPC serialization
• MAP_SHARED treated as MAP_PRIVATE (single-process, so semantically equivalent)
• timeout with dynamic linking — fork+exec with the dynamic linker has issues
• No robust futexes (set_robust_list stub returns 0)
• No clone3 — musl falls back to clone()

Apache License 2.0 — see LICENSE.

Copyright 2025-2026 zw3rk pte. ltd.