add: macOS native support (#3)

* add: Enhance compatibility and extend tests for cross-platform support

- Updated `load_module_file` to handle built-in kernel modules, improving resilience in aarch64/VZ environments.
- Introduced comprehensive backend conformance test suite to validate KVM and VZ implementations.
- Added macOS Virtualization.framework (VZ) backend with detailed configuration support.
- Reorganized shared constants and structures for cross-platform reuse.
- Enhanced protocol with optional version negotiation for better backward compatibility.

* refactor: Simplify control flow, formatting, and function signatures across core components

- Consolidated redundant control flow in `guest-agent`, `control_channel`, and `backend` modules.
- Applied consistent formatting and compact function signatures for improved readability and maintainability.
- Adjusted pre-commit hook path for streamlined formatting validation.
- Enhanced Rust API's argument structures and handling for better clarity.

* refactor: streamline conformance tests and enhance CI for cross-platform support

- Unified backend availability checks with `backend_available` to improve readability and maintainability.
- Replaced KVM-specific checks with a generic VM backend check across conformance tests.
- Expanded GitHub Actions CI matrix to include macOS builds and tests for cross-platform compatibility.
- Introduced dedicated E2E test workflow for macOS Virtualization.framework (VZ) backend.
- Updated test image script to support musl cross-compilation and macOS environment.

* refactor: implement `Default` for `KvmBackend`, simplify control flow, and enhance pre-commit hooks

- Added `Default` implementation for `KvmBackend` to streamline initialization.
- Simplified `is_running` with `is_some_and` and adjusted response handling in async task.
- Enhanced pre-commit hooks to enforce `cargo clippy` checks with warnings as errors.

* update: enforce Linux-only restriction for `guest-agent` and exclude it from macOS CI tasks

- Added compile-time check to ensure `guest-agent` runs only on Linux (as PID 1 inside micro-VMs).
- Updated GitHub Actions workflows to exclude `guest-agent` from macOS builds, tests, and documentation generation.

* update: add `Send + Sync` safety guarantees for `VzBackend` and refactor socket device handling

- Introduced `SendSyncDevice` wrapper for `VZVirtioSocketDevice` to ensure thread safety.
- Implemented `Send` and `Sync` traits for `VzBackend`, with safe access guarantees.
- Refactored connector and initialization logic to utilize the new `SendSyncDevice`.

* update: improve type safety and refactor completion handler logic in `VzBackend`

- Replaced generic `AnyObject` usage with specific `VZSocketDeviceConfiguration` and `VZNetworkDeviceConfiguration` types.
- Ensured thread-safe wrappers for `SendSyncDevice` using `Arc`.
- Refactored completion handler implementation with scoped variables to reduce mutex contention.
- Addressed platform-specific code warnings for non-Linux builds.

* refactor: use `block_in_place` for synchronous `VzBackend` VM setup and improve channel handling

- Replaced async `oneshot` channels with synchronous `std::sync::mpsc::channel` for VM start/stop operations.
- Refactored VM setup logic to execute synchronously via `tokio::task::block_in_place` for ObjC type safety.
- Enhanced logging and streamlined configuration flow for better maintainability.

* remove: drop `boot_diag.rs` example and update related configurations

- Removed the `boot_diag.rs` Linux-specific example to simplify codebase and maintenance.
- Adjusted CI documentation build command to use the `--workspace` flag for consistency.
- Minor cleanup in `VzBackend` to remove unnecessary cast for file descriptor.

* refactor: implement `Default` for `VzBackend` and update inconsistent doc links

- Added `Default` implementation for `VzBackend` to simplify initialization.
- Fixed inconsistent references to `ControlChannel` and `VmmBackend` in documentation comments for improved clarity.

* fix: mark Low-Level VM Access doctest as ignored for macOS compatibility

The doctest references MicroVm and VoidBoxConfig which are Linux-only types,
causing doc-test failures on macOS CI.

* update: add caching for musl-cross toolchain in macOS E2E workflow and increase timeout to 60 mins

- Implemented caching of the musl-cross toolchain to optimize workflow execution.
- Updated timeout for macOS E2E tests to 60 minutes to accommodate longer runs.
- Improved musl-cross installation process with cache utilization and verification steps.

* fix: make Virtualization.framework backend work end-to-end on macOS Apple Silicon

- VZ backend: fix DispatchQueue thread affinity, vsock FD ownership (libc::dup), async streaming exec
- Guest agent: DHCP-first networking for VZ NAT, tmpfs /tmp for sandbox user, relax RLIMIT_AS for Bun
- Cross-build: auto-detect musl toolchain, download ARM64 glibc/busybox from Ubuntu packages
- Refactor build_guest_image.sh into platform-specific modules (lib/guest_{common,linux,macos}.sh)
- Add voidbox.entitlements and .cargo/config.toml for code-signing and cross-compilation
- README: macOS prerequisites and run instructions

* update: streamline kernel download process with helper script and adjust README setup steps

- Added `scripts/download_kernel.sh` for simplified and reusable kernel downloads.
- Refactored README setup steps to utilize the new script, improving clarity and organization.
- Updated test image script to align with musl cross-compilation changes.
- Removed hardcoded kernel version from macOS E2E workflow, delegating version control to the helper script.

* update: improve `VzBackend` VM lifecycle management, add checksum verification, and enhance kernel script

- Refactored `VzBackend` VM lifecycle to ensure thread safety and prevent dangling pointers on timeout or failure.
- Introduced checksum verification for kernel downloads to ensure data integrity.
- Enhanced kernel script with customizable `KERNEL_UPLOAD` version, updated URLs to HTTPS, and added SHA256 checks.
- Adjusted pre-commit hooks to exclude `guest-agent` on macOS for compatibility.

* update: improve kernel extraction to handle zstd-compressed `.deb` packages

- Added support for zstd-compressed archives (`data.tar.zst`) in `scripts/download_kernel.sh`.
- Enhanced error handling for missing or unsupported archive formats.
- Improved compatibility with macOS and older GNU tar versions lacking native zstd support.

* update: refine kernel extraction script, clean imports, and improve pre-commit checks

- Simplified kernel extraction logic with added compatibility for macOS `bsdtar` and refined error handling for `.deb` packages.
- Removed unused `AnyThread` import from `VzBackend`.
- Adjusted pre-commit hook to remove unnecessary stderr redirection for better feedback during Clippy checks.

* add: include `AnyThread` import in `VzBackend` for thread safety improvements

* update: enhance kernel extraction script with improved file detection and error clarity

- Replaced `ls` with `find` for more reliable `data.tar*` detection, ensuring cross-platform compatibility.
- Refined error message for missing `data.tar` to improve user feedback during `.deb` extraction.

* update: configure `tokio::test` to use multi-threaded runtime in conformance tests

- Added `flavor = "multi_thread", worker_threads = 2` to all `tokio::test` annotations, improving test execution scalability.

---------
Co-authored-by: Cristian Spinetta <cebspinetta@gmail.com>

Author: dpsoft

.cargo/config.toml

@@ -0,0 +1,5 @@
+[target.aarch64-unknown-linux-musl]
+linker = "aarch64-linux-musl-gcc"
+
+[target.x86_64-unknown-linux-musl]
+linker = "x86_64-linux-musl-gcc"

.githooks/pre-commit

@@ -1,7 +1,15 @@
 #!/usr/bin/env bash
 set -e
-cd "$(git rev-parse --show-toplevel)/void-box"
+cd "$(git rev-parse --show-toplevel)"
 if ! cargo fmt --all -- --check 2>/dev/null; then
     echo "cargo fmt check failed. Run 'cargo fmt --all' and re-commit."
     exit 1
 fi
+CLIPPY_EXCLUDE=""
+if [[ "$(uname -s)" == "Darwin" ]]; then
+    CLIPPY_EXCLUDE="--exclude guest-agent"
+fi
+if ! cargo clippy --workspace --all-targets --all-features $CLIPPY_EXCLUDE -- -D warnings; then
+    echo "clippy check failed. Fix warnings and re-commit."
+    exit 1
+fi

.github/workflows/ci.yml

@@ -12,11 +12,18 @@ env:
 
 jobs:
   test:
-    name: Test
-    runs-on: ubuntu-latest
+    name: Test (${{ matrix.os }} / ${{ matrix.rust }})
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
-        rust: [stable, beta]
+        include:
+          - os: ubuntu-latest
+            rust: stable
+          - os: ubuntu-latest
+            rust: beta
+          - os: macos-latest
+            rust: stable
 
     steps:
       - uses: actions/checkout@v4
@@ -46,14 +53,28 @@ jobs:
           key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
 
       - name: Run tests
-        run: cargo test --workspace --all-features --verbose
+        run: |
+          if [[ "${{ runner.os }}" == "macOS" ]]; then
+            cargo test --workspace --exclude guest-agent --all-features --verbose
+          else
+            cargo test --workspace --all-features --verbose
+          fi
 
       - name: Run doc tests
-        run: cargo test --doc --workspace --all-features
+        run: |
+          if [[ "${{ runner.os }}" == "macOS" ]]; then
+            cargo test --doc --workspace --exclude guest-agent --all-features
+          else
+            cargo test --doc --workspace --all-features
+          fi
 
   lint:
-    name: Lint
-    runs-on: ubuntu-latest
+    name: Lint (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
 
     steps:
       - uses: actions/checkout@v4
@@ -64,17 +85,24 @@ jobs:
           components: rustfmt, clippy
 
       - name: Check formatting
+        if: matrix.os == 'ubuntu-latest'
         run: cargo fmt --all -- --check
 
       - name: Run clippy
-        run: cargo clippy --workspace --all-targets --all-features -- -D warnings
+        run: |
+          if [[ "${{ runner.os }}" == "macOS" ]]; then
+            cargo clippy --workspace --exclude guest-agent --all-targets --all-features -- -D warnings
+          else
+            cargo clippy --workspace --all-targets --all-features -- -D warnings
+          fi
 
   build:
-    name: Build
+    name: Build (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
-        os: [ubuntu-latest]
+        os: [ubuntu-latest, macos-latest]
         rust: [stable]
 
     steps:
@@ -95,8 +123,12 @@ jobs:
         run: cargo build --release --examples
 
   docs:
-    name: Documentation
-    runs-on: ubuntu-latest
+    name: Documentation (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
 
     steps:
       - uses: actions/checkout@v4
@@ -105,13 +137,22 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Build documentation
-        run: cargo doc --no-deps --all-features
+        run: |
+          if [[ "${{ runner.os }}" == "macOS" ]]; then
+            cargo doc --workspace --no-deps --all-features --exclude guest-agent
+          else
+            cargo doc --no-deps --all-features
+          fi
         env:
           RUSTDOCFLAGS: -D warnings
 
   msrv:
-    name: Minimum Supported Rust Version
-    runs-on: ubuntu-latest
+    name: MSRV (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
 
     steps:
       - uses: actions/checkout@v4
@@ -122,7 +163,12 @@ jobs:
           toolchain: "1.83"
 
       - name: Check build with MSRV
-        run: cargo build --workspace --all-features
+        run: |
+          if [[ "${{ runner.os }}" == "macOS" ]]; then
+            cargo build --workspace --exclude guest-agent --all-features
+          else
+            cargo build --workspace --all-features
+          fi
 
   security:
     name: Security Audit

.github/workflows/e2e-macos.yml

@@ -0,0 +1,88 @@
+name: E2E macOS (Virtualization.framework)
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  e2e-macos:
+    name: E2E VZ (macOS Apple Silicon)
+    runs-on: macos-14
+    timeout-minutes: 60
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # ---- System dependencies ----
+      - name: Cache musl-cross toolchain
+        id: cache-musl
+        uses: actions/cache@v4
+        with:
+          path: |
+            /opt/homebrew/Cellar/musl-cross
+            /opt/homebrew/opt/musl-cross
+            /opt/homebrew/bin/aarch64-linux-musl-*
+          key: ${{ runner.os }}-musl-cross-1
+
+      - name: Install musl cross-compilation toolchain
+        if: steps.cache-musl.outputs.cache-hit != 'true'
+        run: |
+          brew install filosottile/musl-cross/musl-cross
+
+      - name: Relink musl-cross from cache
+        if: steps.cache-musl.outputs.cache-hit == 'true'
+        run: |
+          brew link musl-cross 2>/dev/null || true
+
+      - name: Verify musl-cross
+        run: |
+          which aarch64-linux-musl-gcc
+          aarch64-linux-musl-gcc --version
+
+      # ---- Rust toolchain ----
+      - name: Install Rust stable + aarch64 musl target
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-unknown-linux-musl
+
+      # ---- Cargo cache ----
+      - name: Cache cargo registry + build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-e2e-vz-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-e2e-vz-
+
+      # ---- Build test initramfs ----
+      - name: Build test initramfs (guest-agent + claudio)
+        run: scripts/build_test_image.sh
+
+      # ---- Download prebuilt arm64 Linux kernel ----
+      - name: Download arm64 Linux kernel
+        run: |
+          scripts/download_kernel.sh
+          cp target/vmlinuz-arm64 /tmp/void-box-kernel
+
+      # ---- Run conformance tests ----
+      - name: Run conformance E2E tests
+        env:
+          VOID_BOX_KERNEL: /tmp/void-box-kernel
+          VOID_BOX_INITRAMFS: /tmp/void-box-test-rootfs.cpio.gz
+        run: |
+          echo "Kernel: $VOID_BOX_KERNEL"
+          echo "Initramfs: $VOID_BOX_INITRAMFS"
+          ls -la "$VOID_BOX_KERNEL"
+          ls -la "$VOID_BOX_INITRAMFS"
+
+          # Run conformance tests (--ignored to include VM tests, sequential to avoid resource contention)
+          cargo test --test conformance -- --ignored --test-threads=1

CONTRIBUTING.md

@@ -29,7 +29,7 @@ Thank you for your interest in contributing to void-box! This document provides
 Enable the project's pre-commit hook to catch formatting issues before they reach CI:
 
 ```bash
-git config core.hooksPath void-box/.githooks
+git config core.hooksPath .githooks
 ```
 
 This runs `cargo fmt --all -- --check` on every commit.