Run software built for another world.
An experimental binary runtime with its own CPU engine, loaders and OS compatibility layers.

Website  ·  Download  ·  Quick start  ·  Compatibility  ·  Roadmap

_{Zig 0.16.0   /   macOS + Linux hosts   /   Apache-2.0}

What works today

UNIVERSE executes foreign machine code on an ARM64 Mac using its own Zig interpreter and optional ARM64 JIT. Its loaders read Linux ELF64, Windows PE32+ and library-free macOS Mach-O64 binaries. The runtime implements CPU and OS compatibility itself.

The useful milestone is already here: unchanged downloaded applications run. The tests check their output, exit status and real file bytes in both engines.

Execution is verified on Apple M2 / macOS ARM64. Linux-host builds are cross-compiled; Linux-host execution remains unverified. Compatibility is experimental and varies by application. See the exact supported profile.

Quick start

Install Zig 0.16.0 and Python 3, then build and run a tiny foreign guest:

git clone https://github.com/OthmaneBlial/universe.git
cd universe
zig build -Doptimize=ReleaseSafe
python3 scripts/fixtures.py --arch x86_64
./zig-out/bin/universe artifacts/guests/x86_64/hello-asm
# Hello from x86-64 Linux!

On an ARM64 host, add --jit to enable the optional JIT. Unsupported operations still stop with a named error, guest address and instruction bytes. Guest exit codes pass through; runtime faults return 125.

Try a real application

Download scripts verify pinned upstream checksums. Guest applications stay in artifacts/ and are not bundled with UNIVERSE.

Read JSON with Linux jq:

python3 scripts/public-apps.py
printf '{"answer":42}\n' | ./zig-out/bin/universe artifacts/public-apps/jq '.answer'
# 42

Run dynamic GNU coreutils with Debian's original libraries:

python3 scripts/debian.py --coreutils
printf 'z\na\nb\n' | ./zig-out/bin/universe --allow-files \
  --sysroot artifacts/debian-coreutils-amd64/sysroot \
  artifacts/debian-coreutils-amd64/sysroot/usr/bin/sort
# a
# b
# z

Create an archive with Windows 7-Zip:

python3 scripts/public-apps.py --windows
./zig-out/bin/universe --allow-files artifacts/public-apps/7za.exe \
  a -tzip -mmt=off -mx=1 artifacts/readme.zip README.md
# Everything is Ok

Downloaded application checks · Debian/glibc · Windows compatibility

How it works

ELF / PE / Mach-O
        ↓
Checked guest memory → CPU decoder → Universal IR
                                         ↓
                              Interpreter / ARM64 JIT
                                         ↓
                              OS compatibility layer
                                         ↓
                                  Host services

Guest Linux threads have separate CPU/TLS state and futex wait queues. Forked processes have private memory and descriptors, with shared execution limits. Windows guests use UNIVERSE's API implementations and execute their own DLL, TLS and supported C++ cleanup/catch code. macOS guests currently use a small Darwin syscall subset; dyld and LibSystem remain unsupported.

Architecture · CPU baseline · Guest memory · Threads · Processes · JIT · macOS

Inspect and debug

./zig-out/bin/universe inspect artifacts/guests/x86_64/hello-asm
./zig-out/bin/universe inspect --ir --count 8 artifacts/guests/x86_64/hello-asm
./zig-out/bin/universe --stats --jit artifacts/guests/x86_64/hello-asm
./zig-out/bin/universe debug artifacts/guests/x86_64/hello-asm

The debugger supports stepping, breakpoints, registers, memory, stack, disassembly, IR and syscall inspection. Debugger commands.

Verify locally

./scripts/check.sh

The full local check rebuilds source guests, checks CPU/API behavior and output against independent oracles, compares both engines and runs bounded fuzzing. Optional downloaded-app suites run separately after fetching their inputs:

python3 tests/public-apps.py
python3 tests/public-apps.py --windows
python3 tests/debian.py
python3 tests/coreutils.py

Run python3 scripts/debian.py before the Hello suite. GitHub Actions remains disabled; validation runs locally. Validation evidence · Measured benchmarks.

Boundaries

Experimental compatibility. Supported workflows do not establish broad Windows, Linux or macOS application support, a complete ISA or native performance. The JIT remains opt-in. Compatibility and limits.

Files are opt-in. The guest environment is empty unless --env is supplied. --allow-files grants access with the host user's permissions, including writes. The runtime is not a security sandbox. Security profile.

Contribute

Bring a small failing guest, a reproducible command and an expected result. Open an issue or follow the roadmap.

Apache-2.0 · Third-party notices