Add apple-container sandbox runtime contract and fail-closed validation

.github/aw/agent-runtime-instructions.md

@@ -13,20 +13,25 @@ Use these instructions when creating or updating workflows that mention Docker,
 - Set `sandbox.agent.runtime: gvisor` only when the runner has a local Docker daemon and can install or already has `runsc`.
 - Set `sandbox.agent.runtime: docker-sbx` only when the runner supports KVM-backed microVMs.
 - Set `sandbox.agent.runtime: cloud-hypervisor` only for the preview microVM runtime on a GitHub-hosted Ubuntu x86_64 runner with `/dev/kvm`; prefer `docker-sbx` or `gvisor` when those host constraints are not guaranteed.
+- Set `sandbox.agent.runtime: apple-container` only for the preview Apple Virtualization.framework microVM runtime on a self-hosted bare-metal Apple Silicon runner (Darwin arm64, macOS 26+, `kern.hv_support=1`). It also requires `runs-on: [self-hosted, macOS, ARM64]` and an AWF version that supports the preview; do not generate it otherwise.
 - Do not set `sandbox.agent.runtime: docker`; Docker is selected by omitting the field.
 - Do not set `sandbox.agent.runtime: sbx`; `sbx` is not a valid `sandbox.agent.runtime` value.
 - Set `runner.topology: arc-dind` for ARC or equivalent Kubernetes runners that use a Docker-in-Docker sidecar. This is a runner topology, not an agent runtime.
 
 ## Compatibility
 
-- Do not combine `runner.topology: arc-dind` with `sandbox.agent.runtime: gvisor`, `sandbox.agent.runtime: docker-sbx`, or `sandbox.agent.runtime: cloud-hypervisor`.
+- Do not combine `runner.topology: arc-dind` with `sandbox.agent.runtime: gvisor`, `sandbox.agent.runtime: docker-sbx`, `sandbox.agent.runtime: cloud-hypervisor`, or `sandbox.agent.runtime: apple-container`.
 - ARC DinD workflows must be rootless: do not add `sudo`, `apt-get install`, or other host package bootstrap steps.
 - Docker sbx requires KVM and normally does not work on ARC DinD because the sbx daemon must run on the runner host.
 - Cloud Hypervisor requires `RUNNER_ENVIRONMENT=github-hosted`, Ubuntu Linux x86_64, and `/dev/kvm`; it is not supported on self-hosted or ARC DinD runners.
+- Apple Container is the inverse: it requires a self-hosted bare-metal Apple Silicon runner and is never valid on a GitHub-hosted `macos-*` label, because those runners are virtual machines without nested virtualization.
+- Apple Container rejects host access, `allow-host-ports`, GitHub Actions `services:` port mappings, enclaves, volume mounts, `filesystem.allowWrite`, `ssl_bump`, Vertex AI credential isolation, and `runtime-install`.
+- Apple Container keeps Docker for the AWF infrastructure containers; only the agent workload moves to the Apple Container runtime.
 
 ## `runtime-install`
 
 - `sandbox.agent.runtime-install` defaults to `true` for gVisor and Docker sbx provisioning.
+- `sandbox.agent.runtime-install` is not valid with `cloud-hypervisor` or `apple-container`.
 - Set `runtime-install: false` only when the runner image or pod is pre-provisioned with the runtime and required daemon or policy.
 - When any imported workflow sets `runtime-install: false`, false wins during import merging.
 - With `runtime-install: false`, gh-aw skips generated runtime checks and setup, so the runner must already satisfy those prerequisites.

docs/public/editor/autocomplete-data.json

@@ -886,6 +886,11 @@
                   "type": "string",
                   "desc": "Docker-in-Docker staging image required when raw AWF arguments enable directory or engine-binary pre-staging.",
                   "leaf": true
+                },
+                "appleInit": {
+                  "type": "string",
+                  "desc": "Apple Container guest init image carrying the capability relay.",
+                  "leaf": true
                 }
               }
             },
@@ -903,7 +908,7 @@
             "runtime": {
               "type": "string",
               "desc": "Sandbox runtime profile for the agent container.",
-              "enum": ["docker", "docker-sudo-iptables", "gvisor", "docker-sbx", "cloud-hypervisor"],
+              "enum": ["docker", "docker-sudo-iptables", "gvisor", "docker-sbx", "cloud-hypervisor", "apple-container"],
               "leaf": true
             },
             "runtime-install": {

docs/src/content/docs/reference/frontmatter-full.md

@@ -2236,6 +2236,11 @@ sandbox:
       # (optional)
       dindStaging: "example-value"
 
+      # Apple Container guest init image carrying the capability relay. Required
+      # whenever sandbox.agent.runtime is 'apple-container'.
+      # (optional)
+      appleInit: "example-value"
+
     # Enable or disable model fallback for unresolved model selections. Set to false
     # for BYOK Azure OpenAI deployments to prevent deployment-name rewriting. Supports
     # literal boolean or GitHub Actions expression.
@@ -2263,9 +2268,14 @@ sandbox:
     # (requires DOCKER_PAT and DOCKER_USERNAME secrets and a KVM-capable runner; the
     # compiler handles the required privileged setup); 'cloud-hypervisor' runs the
     # agent in AWF's preview Cloud Hypervisor microVM runtime on GitHub-hosted Ubuntu
-    # x86_64, sized at 2 vCPUs and 4096 MiB. Omitting runtime is equivalent to
-    # 'docker'. gvisor, docker-sbx and cloud-hypervisor are incompatible with
-    # runner.topology: arc-dind.
+    # x86_64, sized at 2 vCPUs and 4096 MiB; 'apple-container' runs the agent in AWF's
+    # preview Apple Virtualization.framework microVM (gh-aw-firewall#7764) and
+    # requires a self-hosted bare-metal Apple Silicon runner (Darwin arm64, macOS 26+,
+    # kern.hv_support=1) declared as runs-on: [self-hosted, macOS, ARM64] —
+    # GitHub-hosted macos-* runners are rejected because nested virtualization is
+    # unavailable, and it needs an AWF version that supports the preview. Omitting
+    # runtime is equivalent to 'docker'. gvisor, docker-sbx, cloud-hypervisor and
+    # apple-container are incompatible with runner.topology: arc-dind.
     # (optional)
     runtime: "docker"
 

pkg/constants/version_constants.go

@@ -109,6 +109,23 @@ const AWFContainerRuntimeMinVersion Version = "v0.27.30"
 // cloud-hypervisor preview runtime and its release assets.
 const AWFCloudHypervisorMinVersion Version = "v0.28.1"
 
+// AWFAppleContainerMinVersion is the minimum AWF version that supports the
+// apple-container preview runtime (Apple Virtualization.framework workloads on
+// self-hosted bare-metal Apple Silicon).
+//
+// The backend is added by gh-aw-firewall#7764, which is not part of any published
+// release yet: the newest release at the time of writing (v0.28.8) still ships a
+// container.containerRuntime enum without "apple-container" and has no
+// appleContainer config section. v0.28.9 is therefore the earliest release that
+// can contain it.
+//
+// This constant is deliberately ABOVE DefaultFirewallVersion so the runtime fails
+// closed by default: a workflow must explicitly pin sandbox.agent.version (or
+// firewall.version) to an AWF build that actually understands the runtime. If
+// gh-aw-firewall#7764 lands in a later release than v0.28.9, bump this constant —
+// never lower it, and never relax the gate to DefaultFirewallVersion.
+const AWFAppleContainerMinVersion Version = "v0.28.9"
+
 // AWFLegacySecurityMinVersion is the minimum AWF version that supports the
 // --legacy-security flag and unconditional API proxy (gh-aw-firewall#6207).
 // Workflows pinning an older AWF version must use the old --security-mode compat behavior.

pkg/parser/schemas/main_workflow_schema.json

@@ -3744,6 +3744,10 @@
                         "dindStaging": {
                           "$ref": "#/$defs/awf_pinned_image",
                           "description": "Docker-in-Docker staging image required when raw AWF arguments enable directory or engine-binary pre-staging."
+                        },
+                        "appleInit": {
+                          "$ref": "#/$defs/awf_pinned_image",
+                          "description": "Apple Container guest init image carrying the capability relay. Required whenever sandbox.agent.runtime is 'apple-container'."
                         }
                       },
                       "examples": [
@@ -3766,10 +3770,10 @@
                     },
                     "runtime": {
                       "type": "string",
-                      "description": "Sandbox runtime profile for the agent container. Each value selects one supported security and topology profile: 'docker' (default) runs the agent under Docker with a rootless AWF and network isolation; 'docker-sudo-iptables' runs Docker with a privileged AWF, legacy iptables networking, and host/service access (required for allow-host-ports and GitHub Actions services: connectivity); 'gvisor' runs the agent under gVisor's runsc runtime with strict network isolation; 'docker-sbx' runs the agent inside a Docker sbx KVM microVM (requires DOCKER_PAT and DOCKER_USERNAME secrets and a KVM-capable runner; the compiler handles the required privileged setup); 'cloud-hypervisor' runs the agent in AWF's preview Cloud Hypervisor microVM runtime on GitHub-hosted Ubuntu x86_64, sized at 2 vCPUs and 4096 MiB. Omitting runtime is equivalent to 'docker'. gvisor, docker-sbx and cloud-hypervisor are incompatible with runner.topology: arc-dind.",
-                      "enum": ["docker", "docker-sudo-iptables", "gvisor", "docker-sbx", "cloud-hypervisor"],
+                      "description": "Sandbox runtime profile for the agent container. Each value selects one supported security and topology profile: 'docker' (default) runs the agent under Docker with a rootless AWF and network isolation; 'docker-sudo-iptables' runs Docker with a privileged AWF, legacy iptables networking, and host/service access (required for allow-host-ports and GitHub Actions services: connectivity); 'gvisor' runs the agent under gVisor's runsc runtime with strict network isolation; 'docker-sbx' runs the agent inside a Docker sbx KVM microVM (requires DOCKER_PAT and DOCKER_USERNAME secrets and a KVM-capable runner; the compiler handles the required privileged setup); 'cloud-hypervisor' runs the agent in AWF's preview Cloud Hypervisor microVM runtime on GitHub-hosted Ubuntu x86_64, sized at 2 vCPUs and 4096 MiB; 'apple-container' runs the agent in AWF's preview Apple Virtualization.framework microVM (gh-aw-firewall#7764) and requires a self-hosted bare-metal Apple Silicon runner (Darwin arm64, macOS 26+, kern.hv_support=1) declared as runs-on: [self-hosted, macOS, ARM64] \u2014 GitHub-hosted macos-* runners are rejected because nested virtualization is unavailable, and it needs an AWF version that supports the preview. Omitting runtime is equivalent to 'docker'. gvisor, docker-sbx, cloud-hypervisor and apple-container are incompatible with runner.topology: arc-dind.",
+                      "enum": ["docker", "docker-sudo-iptables", "gvisor", "docker-sbx", "cloud-hypervisor", "apple-container"],
                       "default": "docker",
-                      "examples": ["docker", "docker-sudo-iptables", "gvisor", "docker-sbx", "cloud-hypervisor"]
+                      "examples": ["docker", "docker-sudo-iptables", "gvisor", "docker-sbx", "cloud-hypervisor", "apple-container"]
                     },
                     "runtime-install": {
                       "type": "boolean",