fix(macos): enable voidbox on Apple Silicon via entitlement + kernel … (#6)

* fix(macos): enable voidbox on Apple Silicon via entitlement + kernel decompression

- Add Cargo runner to auto-codesign voidbox before run (required for VZ)
- Decompress gzip kernel in OCI guest images for VZ on macOS ARM64
- Update README with macOS guest-image workflow instructions

* fix clippy errors

Author: cspinetta

.cargo/config.toml

@@ -3,3 +3,10 @@ linker = "aarch64-linux-musl-gcc"
 
 [target.x86_64-unknown-linux-musl]
 linker = "x86_64-linux-musl-gcc"
+
+# macOS: codesign voidbox before run (required for Virtualization.framework)
+[target.aarch64-apple-darwin]
+runner = "scripts/run_voidbox_macos.sh"
+
+[target.x86_64-apple-darwin]
+runner = "scripts/run_voidbox_macos.sh"

README.md

@@ -301,6 +301,18 @@ target/debug/examples/ollama_local
 
 > **Note:** Every `cargo build` invalidates the code signature. Re-run `codesign` after each rebuild.
 
+When using the `voidbox` CLI, `cargo run` automatically codesigns before executing (via `.cargo/config.toml` runner). Just run:
+
+```bash
+cargo run --bin voidbox -- run --file examples/specs/oci/guest-image-workflow.yaml
+```
+
+If running the binary directly (e.g. `./target/debug/voidbox`), codesign manually first:
+
+```bash
+codesign --force --sign - --entitlements voidbox.entitlements target/debug/voidbox
+```
+
 ### Parallel pipeline with per-box models
 
 ```bash
@@ -399,7 +411,7 @@ More OCI examples in [`examples/specs/oci/`](examples/specs/oci/):
 | `workflow.yaml` | Workflow with `sandbox.image: alpine:3.20` (no LLM) |
 | `pipeline.yaml` | Multi-language pipeline: Python base + Go and Java OCI skills |
 | `skills.yaml` | OCI skills only (Python, Go, Java) mounted into default initramfs |
-| `guest-image-workflow.yaml` | Workflow using `sandbox.guest_image` for auto-pulled kernel + initramfs |
+| `guest-image-workflow.yaml` | Workflow using `sandbox.guest_image` for auto-pulled kernel + initramfs (on macOS, codesign required; gzip kernel is auto-decompressed for VZ) |
 
 ---
 

scripts/run_voidbox_macos.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Cargo runner for voidbox: on macOS, codesigns the binary before executing.
+# Required because Apple's Virtualization.framework needs com.apple.security.virtualization.
+#
+# Used via .cargo/config.toml [[bin]] runner for voidbox.
+
+set -euo pipefail
+BINARY="$1"
+shift
+
+if [[ "$(uname -s)" == "Darwin" ]]; then
+  ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+  ENTITLEMENTS="${ROOT}/voidbox.entitlements"
+  if [[ -f "$ENTITLEMENTS" ]]; then
+    codesign --force --sign - --entitlements "$ENTITLEMENTS" "$BINARY" 2>/dev/null || true
+  fi
+fi
+
+exec "$BINARY" "$@"

voidbox-oci/src/lib.rs

@@ -148,10 +148,16 @@ impl OciClient {
 
         if blob_cache.has_guest(&cache_key) {
             let guest_dir = blob_cache.guest_path(&cache_key);
-            info!(path = %guest_dir.display(), "using cached guest files");
-            return Ok(GuestImageFiles {
+            let cached = unpack::GuestFiles {
                 kernel: guest_dir.join("vmlinuz"),
                 initramfs: guest_dir.join("rootfs.cpio.gz"),
+            };
+            // On macOS ARM64, decompress gzip kernel if vmlinux not yet present.
+            let guest = unpack::ensure_kernel_uncompressed_for_vz(&cached)?;
+            info!(path = %guest_dir.display(), "using cached guest files");
+            return Ok(GuestImageFiles {
+                kernel: guest.kernel,
+                initramfs: guest.initramfs,
             });
         }
 
@@ -172,6 +178,14 @@ impl OciClient {
                 .await
                 .map_err(|e| OciError::Layer(format!("guest extract task panicked: {}", e)))??;
 
+        // On macOS ARM64, VZ requires uncompressed kernel; decompress if gzip.
+        let guest =
+            tokio::task::spawn_blocking(move || unpack::ensure_kernel_uncompressed_for_vz(&guest))
+                .await
+                .map_err(|e| {
+                    OciError::Layer(format!("kernel decompress task panicked: {}", e))
+                })??;
+
         blob_cache.mark_guest_done(&cache_key).await?;
 
         info!(

voidbox-oci/src/unpack.rs

@@ -30,7 +30,7 @@ pub fn unpack_layers(layers: &[LayerInfo], dest: &Path) -> Result<PathBuf> {
 }
 
 /// Paths to the extracted guest files (kernel + initramfs).
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct GuestFiles {
     pub kernel: PathBuf,
     pub initramfs: PathBuf,
@@ -99,6 +99,47 @@ pub fn extract_guest_files(layers: &[LayerInfo], dest: &Path) -> Result<GuestFil
     })
 }
 
+/// If the kernel is gzip-compressed and we're on macOS ARM64 (VZ backend),
+/// decompress it to vmlinux. Apple's Virtualization.framework requires
+/// uncompressed ARM64 kernels. Returns the path to use for the kernel.
+#[cfg(all(target_os = "macos", target_arch = "aarch64"))]
+pub fn ensure_kernel_uncompressed_for_vz(guest: &GuestFiles) -> Result<GuestFiles> {
+    let kernel_bytes =
+        fs::read(&guest.kernel).map_err(|e| OciError::Layer(format!("read kernel: {}", e)))?;
+
+    // Gzip magic bytes (RFC 1952): 0x1f 0x8b
+    if kernel_bytes.len() < 2 || kernel_bytes[..2] != [0x1f, 0x8b] {
+        return Ok(guest.clone());
+    }
+
+    info!(
+        path = %guest.kernel.display(),
+        "kernel is gzip-compressed; decompressing for VZ (required on macOS ARM64)",
+    );
+
+    let decompressed_path = guest.kernel.parent().unwrap().join("vmlinux");
+    let mut decoder = GzDecoder::new(&kernel_bytes[..]);
+    let mut decompressed = Vec::new();
+    decoder
+        .read_to_end(&mut decompressed)
+        .map_err(|e| OciError::Layer(format!("decompress kernel: {}", e)))?;
+
+    fs::write(&decompressed_path, &decompressed)
+        .map_err(|e| OciError::Layer(format!("write vmlinux: {}", e)))?;
+
+    info!(path = %decompressed_path.display(), "decompressed kernel ready");
+
+    Ok(GuestFiles {
+        kernel: decompressed_path,
+        initramfs: guest.initramfs.clone(),
+    })
+}
+
+#[cfg(not(all(target_os = "macos", target_arch = "aarch64")))]
+pub fn ensure_kernel_uncompressed_for_vz(guest: &GuestFiles) -> Result<GuestFiles> {
+    Ok(guest.clone())
+}
+
 // ---------------------------------------------------------------------------
 // Single layer extraction
 // ---------------------------------------------------------------------------