Build from source
Every build task runs through cargo xtask. Host binaries build directly on macOS, while guest images (kernel, rootfs, and data disk) build reproducibly inside Linux Docker containers.
Prerequisites
Section titled “Prerequisites”- macOS 15 or later on Apple silicon
- Rust via
rustup(rust-toolchain.tomlpins the Rust toolchain and theaarch64-unknown-linux-musltarget) - Go (required for
gvproxyandlibgvproxy.dylibwith cgo) - Xcode command-line tools (for Swift,
codesign, and cgo) - A running Docker engine (for building the Linux kernel, rootfs, and data disk)
Build host binaries and initramfs
Section titled “Build host binaries and initramfs”Compile kat-init for aarch64-unknown-linux-musl, pack guest/out/initramfs.cpio, build gvproxy and libgvproxy.dylib from vendor/patches/gvproxy/, compile katamaran and katamaran-vm in release mode, and ad-hoc sign katamaran-vm with the Hypervisor entitlement:
cargo xtask buildTo build only gvproxy and libgvproxy.dylib:
cargo xtask gvproxyTo build only guest/out/initramfs.cpio:
cargo xtask initramfsBuild guest images
Section titled “Build guest images”Build the Linux kernel (guest/out/Image), the read-only Alpine EROFS rootfs (guest/out/rootfs.erofs), and the sparse btrfs data disk template (guest/out/data.img):
cargo xtask kernelcargo xtask rootfscargo xtask diskEach task uses the active Docker context by default. Set KATAMARAN_BUILD_CONTEXT to target a different Docker context:
KATAMARAN_BUILD_CONTEXT=desktop-linux cargo xtask kernelcargo xtask kernel validates every entry in guest/kernel/katamaran.config, applies guest/kernel/patches/*.patch, builds Image, and gates the build on Moby’s check-config.sh.
Build the macOS app and DMG
Section titled “Build the macOS app and DMG”Build target/Katamaran.app (Swift AppKit binary, generated .icns icon, katamaran, katamaran-vm, libgvproxy.dylib, and guest images, ad-hoc signed):
cargo xtask appBuild a distributable disk image at target/dist/Katamaran-<version>.dmg:
cargo xtask dmgRun a headless smoke check of the built app against a test daemon:
cargo xtask app-smokeRun an isolated development VM
Section titled “Run an isolated development VM”To boot your local build without touching ~/.katamaran or ~/Katamaran, set KATAMARAN_HOME and --mount:
KATAMARAN_HOME=~/.katamaran-dev ./target/release/katamaran run --cpus 4 --memory-mib 4096 --mount ~/Katamaran-devFormat and test
Section titled “Format and test”Format only the katamaran workspace crates (do not run cargo fmt --all, which would reformat vendor/libkrun):
cargo xtask fmtRun fast host unit tests:
cargo test --lib -p kat-proto -p kat-vmm -p kat-daemon -p xtaskRun the full VM integration test suite (boots real VMs):
cargo xtask test-vmRepository layout
Section titled “Repository layout”| Path | Description |
|---|---|
crates/kat-daemon |
katamaran CLI and background daemon |
crates/kat-vmm |
katamaran-vm process wrapping libkrun, in-process gvproxy, and FSEvents cache invalidation |
crates/kat-init |
Guest PID 1 supervising containerd, dockerd, NFS, LXC machines, and memory reclaim |
crates/kat-nfs |
In-guest NFSv3 server exporting Linux files to macOS |
crates/kat-proto |
Wire protocol shared between host and guest |
crates/kat-term |
Terminal library wrapping libghostty-vt for the macOS app |
app |
Swift and AppKit macOS app and icon generator |
xtask |
Workspace build commands (cargo xtask ...) |
guest |
Build scripts, kernel config, and kernel patches |
vendor/libkrun |
Patched libkrun tree (patch series in vendor/patches) |
vendor/patches/gvproxy |
Patch series applied to gvisor-tap-vsock |
docs |
Astro and Starlight documentation website |
bench |
Benchmark tool and saved comparison results |
scripts |
Standalone filesystem and network probe scripts |