A minimal, educational Linux-syscall emulator for Apple Silicon — the gVisor model, but on macOS. A tiny aarch64 program runs inside a VM, and when it issues a syscall the host process services it in userspace instead of forwarding to a real kernel. The whole thing is one file of C++, small enough to hold in your head.
The guest program (hand-encoded aarch64 in hyp.cpp):
movz x0, #1 ; fd = 1 (stdout)
movz x1, #0x100 ; buf = guest address of "hi\n"
movz x2, #3 ; len = 3
movz x8, #64 ; SYS_write
hvc #0 ; trap to host
movz x0, #0 ; status = 0
movz x8, #93 ; SYS_exit
hvc #0When hvc #0 traps the host, we read X8 for the syscall number, X0–X5
for arguments, service the call (real write(2) for SYS_write,
loop-exit for SYS_exit), write the return value back to X0, and resume.
Expected output:
hi
…and a host exit code of 0, propagated from the guest's exit(0).
gVisor is a Google sandbox: it runs Linux
applications by pairing them with a userspace kernel that intercepts
their syscalls. The application thinks it's talking to Linux; really
it's talking to gVisor's Sentry process. nanovisor is the same idea
on macOS, using Hypervisor.framework as the syscall-trap mechanism.
The dispatch loop in hyp.cpp is the actual irreducible core of any
gVisor-style userspace kernel:
- Run the guest natively.
- Catch every trap.
- Decode it as a Linux syscall (number in X8, args in X0–X5).
- Service it on the host.
- Write the return value back to X0.
- Resume.
Adding more syscalls is just more case arms.
This is commit 1 of the pivot from "minimal hypervisor demo" to "gVisor-on-macOS." Two corners are deliberately cut:
- Trap instruction. A real Linux/aarch64 program issues syscalls
with
svc #0. Routing svc to the host requires either an EL1 vector table that forwards viahvc, orHCR_EL2.TGE. For now the guest runs at EL1 and useshvc #0directly — same Linux ABI in the registers, but a non-Linux trap instruction. - Memory translation. The guest runs with the MMU off, so guest virtual = guest physical, mapped 1:1 to a single host page. No page-table walks yet.
What's planned, in order:
- Real EL0/EL1 split. Add a 16-entry EL1 vector table whose
entries forward to the host via
hvc, plus a boot stub thaterets into EL0. Switch the guest tosvc #0. Now we have actual privilege separation between the guest and our userspace kernel. - More syscalls.
read,openat,close,mmap,brk,clock_gettime, etc. Enough to run a static "hello, world" built with musl. - ELF loader. Read a static-pie aarch64 ELF off disk, set up guest memory, build the auxv/argv/envp on the guest stack.
- Multiple pages, MMU on. A real address space with code/data/heap regions and proper translation.
- Apple Silicon Mac (M1 or later)
- Xcode Command Line Tools:
xcode-select --install
make runThe Makefile compiles hyp.cpp and ad-hoc codesigns the binary with
the com.apple.security.hypervisor entitlement. Without that
entitlement, hv_vm_create returns HV_DENIED.
make testRuns tests.sh, which execs ./hyp with each of several built-in
guest programs (see kPrograms[] in hyp.cpp) and asserts the
resulting stdout and exit code. Five cases today: happy path, exit-code
propagation, out-of-bounds buffer rejected with -EFAULT, unknown
syscall rejected with -ENOSYS, and bad argv handling.
| File | What's in it |
|---|---|
hyp.cpp |
The whole emulator. Heavily commented; read top-to-bottom. |
hyp.entitlements |
Grants com.apple.security.hypervisor. Required by macOS. |
tests.sh |
Integration tests; run with make test. |
Makefile |
Compile + ad-hoc codesign. |
The 8 numbered steps inside hyp.cpp map 1:1 to the lifecycle:
hv_vm_create— ask macOS to allow this process to run guestsmmap— allocate page-aligned host memory to back the guest's RAM- Lay out guest code and data (the program above, plus
"hi\n") hv_vm_map— install stage-2 page tables so the guest can see themhv_vcpu_create— make a virtual CPUhv_vcpu_set_reg— set PC and PSTATE- The syscall dispatch loop
hv_vcpu_destroy/hv_vm_unmap/hv_vm_destroy— tear down
On ARMv8 the CPU runs at one of four privilege levels:
| Level | Typical occupant |
|---|---|
| EL0 | userspace processes |
| EL1 | kernel |
| EL2 | hypervisor |
| EL3 | secure monitor (firmware/boot) |
macOS itself runs at EL2 and exposes Hypervisor.framework as the
user-mode control surface for guest VMs. When you call hv_vcpu_run,
macOS programs the EL2 control registers, drops the CPU into EL1, and
lets the guest execute natively until something traps back into EL2.
In a gVisor-style design you ideally want the guest at EL0 (so it has no privilege to disable interrupts, install vectors, or touch system registers) with a thin EL1 trampoline that forwards every exception to the userspace kernel. Commit 1 keeps the guest at EL1 for simplicity; commit 2 introduces the real EL0/EL1 split.
- gVisor design docs — particularly the "Platform" doc that covers ptrace vs. KVM as syscall-trap mechanisms. nanovisor's Hypervisor.framework path is closest to gVisor's KVM platform.
- ARM Architecture Reference Manual — chapters on Exception Levels and AArch64 Virtualization.
- Hypervisor.framework documentation
- Linux kernel
include/uapi/asm-generic/unistd.h— the canonical syscall-number table we're emulating.
MIT — Copyright (c) 2026 Maruf Zaber