From 74de5efbf7cf2133912c881f27f5fb104de72af7 Mon Sep 17 00:00:00 2001 From: "Jiaxiao (mossaka) Zhou" Date: Sat, 21 Feb 2026 01:12:37 +0000 Subject: [PATCH] docs: update runner and architecture compatibility Update the compatibility matrix with tested runner configurations: - ubuntu-24.04-arm (ARM64) now fully supported - macOS runners explicitly marked as not supported with explanation - Windows runners marked as not supported - ARM64 architecture upgraded from "May Work" to "Fully Supported" Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/compatibility.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/compatibility.md b/docs/compatibility.md index a463ded0..35438993 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -34,17 +34,26 @@ The minimum Node.js version is specified in `package.json` under `engines.node: ### GitHub Actions Runners -The firewall is tested on GitHub Actions runners with the following configurations: +| Runner | Architecture | Status | Notes | +|--------|-------------|--------|-------| +| `ubuntu-latest` | x86_64 | ✅ Fully Supported | Currently Ubuntu 24.04. Primary CI runner. | +| `ubuntu-24.04` | x86_64 | ✅ Fully Supported | Explicit Ubuntu 24.04 (Noble). | +| `ubuntu-22.04` | x86_64 | ✅ Fully Supported | Ubuntu 22.04 (Jammy) LTS. | +| `ubuntu-24.04-arm` | arm64 | ✅ Fully Supported | Linux ARM64. Docker, AWF, and MCP Gateway all work. | +| `macos-latest` | arm64 | ❌ Not Supported | macOS runners are VMs without nested virtualization — Docker cannot run. See below. | +| `macos-*` (any) | arm64/x86_64 | ❌ Not Supported | Same limitation as above. | +| `windows-*` | x86_64 | ❌ Not Supported | AWF requires Linux iptables and Docker with Linux containers. | -- `ubuntu-latest` (currently Ubuntu 24.04) -- `ubuntu-22.04` +### Why macOS runners are not supported + +GitHub-hosted macOS runners are themselves virtual machines (`Apple M1 (Virtual)`) that do not support nested virtualization. AWF requires Docker for the Squid proxy container, agent container, and MCP Gateway — all of which need a Linux VM on macOS. Docker Desktop, colima (with both `vz` and `qemu` VM types), and Apple's `container` tool were all tested and none can provide Docker on these runners. The root cause error is: `Virtualization is not available on this hardware`. ### Architecture | Architecture | Status | Notes | |--------------|--------|-------| | x86_64 (amd64) | ✅ Fully Supported | Primary development platform | -| arm64 (aarch64) | ⚠️ May Work | Not actively tested | +| arm64 (aarch64) | ✅ Fully Supported | Tested on `ubuntu-24.04-arm` GitHub Actions runners | ## CI Test Matrix