Skip to content

docs: update runner and architecture compatibility #992

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Mossaka wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: update runner and architecture compatibility #992

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions docs/compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Copy link

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The note "Tested on ubuntu-24.04-arm GitHub Actions runners" is not supported by evidence in the codebase. No CI workflows are configured to run on ARM runners, and there's no test output or workflow history included that demonstrates successful ARM64 testing.

Consider revising to accurately reflect the testing status, such as: "Multi-arch containers built; manual testing required" or provide evidence of the testing (e.g., workflow runs, test results) if it was done outside the repository's CI system.

This issue also appears on line 42 of the same file.

Copilot uses AI. Check for mistakes.

## CI Test Matrix

Expand Down
Loading