feat: add macOS support via vfkit hypervisor

.github/workflows/ci.yml

@@ -8,8 +8,11 @@ on:
 
 jobs:
   test:
-    name: Test
-    runs-on: ubuntu-latest
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
     steps:
       - uses: actions/checkout@v4
       - name: Install Nix
@@ -26,7 +29,6 @@ jobs:
   e2e:
     name: E2E
     runs-on: ubuntu-latest
-    continue-on-error: true
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4

README.md

@@ -1,6 +1,6 @@
 # nixbox
 
-Cloud-hypervisor microVM sandbox for running AI agents (eg: Claude Code with `--dangerously-skip-permissions`) in full isolation. Host protected by KVM boundary + egress filtering. Directories shared via virtiofs bind mounts.
+MicroVM sandbox for running AI agents (eg: Claude Code with `--dangerously-skip-permissions`) in full isolation. Host protected by hypervisor boundary + egress filtering. Directories shared via virtiofs bind mounts. Supports Linux (cloud-hypervisor) and macOS on Apple Silicon (vfkit / Virtualization.framework).
 
 Multiple VMs can run concurrently (up to 64), each with isolated slot-based networking. Mount your entire workspace (e.g. `~/workspace`) rather than a single project — this lets you switch between projects inside the VM without restarting it.
 
@@ -15,10 +15,18 @@ Multiple VMs can run concurrently (up to 64), each with isolated slot-based netw
 
 ## Prerequisites
 
-- Linux with KVM (`/dev/kvm`)
+### Linux
+
+- KVM (`/dev/kvm`)
 - [Nix](https://nixos.org/download/) with flakes enabled
 - `dnsmasq`, `nftables`, `e2fsprogs` (for `mke2fs`), `virtiofsd`
 
+### macOS (Apple Silicon)
+
+- macOS 13+ (Ventura) with Virtualization.framework
+- [Nix](https://nixos.org/download/) with flakes enabled
+- `e2fsprogs` (for `mke2fs`)
+
 ## Install
 
 ```bash
@@ -258,6 +266,14 @@ The JDK is specified separately via `nix.packages` so you control the version. S
 - **virtiofs + `O_TMPFILE`** — virtiofs does not support `O_TMPFILE`. Tools that hit this (e.g. Node.js/Claude Code) need tmpfs overlays on affected dirs — the `claude-code` plugin handles this automatically.
 - **Claude Code conversations** — Claude Code stores conversations under `~/.claude/projects/` keyed by the workspace's absolute path. Since the workspace path differs between host and guest (e.g. `/home/you/workspace` vs `/home/vmuser/workspace`), conversations don't carry over between the two. Workaround: symlink the guest-side conversation directory to the host's.
 
+### macOS-specific limitations
+
+- **Network filtering** — `filtered` mode is not yet implemented on macOS. Only `open` mode works; `off` and `filtered` will error.
+- **Hot-plug mounts** — `nixbox mount` / `nixbox unmount` are not supported. Declare mounts in `config.nix` and restart the VM.
+- **Guest IP discovery** — uses ARP scan after boot instead of static assignment. Boot may be slightly slower.
+
+See [ADR 015](docs/decisions/015-macos-vfkit-support.md) for full platform comparison.
+
 ## Acknowledgments
 
 - Built on [microvm.nix](https://github.com/microvm-nix/microvm.nix)