What's Changed
Documentation
- [docs] auth: GHEC Copilot auth header prefix corrected to token by @github-actions[bot] in #7120
- [docs] auth: Mark gh-aw#50053 MCP OIDC boundary work as resolved by @github-actions[bot] in #7156
- [docs] sbx/gVisor: Sync sbx-integration.md with the Firecracker microVM backend by @github-actions[bot] in #7174
- [docs] auth: auth: clarify Actions OIDC variables also forward for OTLP workload identity by @github-actions[bot] in #7248
Other Changes
- docs: Sync schemas and specs with source changes by @github-actions[bot] in #6950
- chore: update model-to-API mapping (2026-08-05) by @github-actions[bot] in #6951
- Upgrade gh-aw to v0.85.0 pre-release and recompile workflows by @lpcox in #6957
- fix: translate safeoutputs mount for ARC/DinD by @lpcox with @Copilot in #6959
- refactor: share bounded preflight runtime probes by @lpcox with @Copilot in #6960
- refactor: share sbx ingress capability writer by @lpcox with @Copilot in #6961
- chore(deps): safe patch updates incl. ajv 8.20.0 security fix by @lpcox with @Copilot in #6962
- fix(api-proxy): honor configured providers in model steering by @lpcox with @Copilot in #6963
- fix: propagate config fields to all layers by @github-actions[bot] in #6970
- chore: upgrade gh-aw to v0.85.1 pre-release and recompile workflows by @lpcox in #6985
- fix(api-proxy): stop alias fallback picking arbitrary models by @davidslater in #6996
- feat: add unified enclave foundation by @lpcox in #6986
- chore: upgrade gh-aw to v0.86.0 pre-release and recompile workflows by @lpcox in #7027
- feat: add enclave MCP script executor by @lpcox in #6988
- feat: add enclave agent executor by @lpcox in #6990
- feat: route unified enclaves exclusively through mcpg by @lpcox in #6992
- refactor: remove legacy bounded execution in favor of MCP enclaves by @lpcox in #6994
- fix(api-proxy): correct auth prefix for derived GHEC Copilot targets by @lpcox with @Copilot in #6991
- Share bounded ingress conformance test harness by @lpcox with @Copilot in #6987
- Add A19/B19 runner doctor entries: ARC/DinD safeoutputs mount + rootless cleanup chmod noise by @lpcox with @Copilot in #7067
- fix: propagate config fields to all layers by @github-actions[bot] in #7054
- Fix cli-proxy ENETUNREACH in network-isolation mode by dual-homing it on the external bridge by @lpcox with @Copilot in #7066
- Add SBX rollout failure monitor by @lpcox in #7096
- Upgrade gh-aw to v0.86.1 pre-release and recompile workflows by @lpcox in #7115
- Bump eslint, globals, js-yaml, and typescript-eslint patch versions by @lpcox with @Copilot in #7116
- Update Runner Doctor with C9 and B20 failure modes by @lpcox with @Copilot in #7124
- Upgrade gh-aw extension to latest pre-release and recompile workflows by @lpcox in #7146
- docs: clarify /usr/local read-only mount and hardcoded-binary-path workarounds by @lpcox with @Copilot in #7151
- Confirm --allow-host-ports works standalone with --enable-host-access in strict security mode by @lpcox with @Copilot in #7152
- Drive Google provider adapters (Gemini, Vertex) from declarative specs by @lpcox with @Copilot in #7153
- Add configurable --pids-limit and expose delegated cgroup in agent sandbox by @lpcox with @Copilot in #7150
- Refactor external agent runtime lifecycle by @lpcox in #7129
- Add Firecracker control-plane preview by @lpcox in #7133
- Enforce isolated networking for Firecracker by @lpcox in #7134
- feat: add Firecracker guest execution transport by @lpcox in #7135
- feat: integrate Firecracker primary-agent runtime preview by @lpcox in #7136
- feat: complete Firecracker preview rollout coverage by @lpcox in #7138
- ci: run Firecracker live smoke on hosted Ubuntu by @lpcox in #7194
- Add B21/B22/B23 self-hosted failure-mode lessons to runner-doctor catalog by @lpcox with @Copilot in #7175
- Retain reachable DNS resolvers in network-isolation mode by @lpcox with @Copilot in #7188
- Make external runtime dependency type module-private by @lpcox with @Copilot in #7189
- Remove unused export of ExternalRuntimeBackendFactory type by @lpcox with @Copilot in #7193
- Make
isNonPortableDnsinternal todns-resolverby @lpcox with @Copilot in #7192 - Make runtime factory context module-private by @lpcox with @Copilot in #7190
- Internalize unused
ExternalRuntimeBackendRegistrytype export by @lpcox with @Copilot in #7191 - Extract VMM-neutral microVM foundation from src/firecracker (stack layer 1) by @lpcox in #7212
- Add Cloud Hypervisor v53.0 configuration/artifact foundation (stack layer 2) by @lpcox in #7222
- feat: implement a runnable Cloud Hypervisor v53.0 microVM backend (stack layer 3) by @lpcox in #7225
- ci: add Cloud Hypervisor live-KVM integration by @lpcox in #7227
- chore: upgrade gh-aw to v0.86.1 (pre-release) and recompile workflows by @lpcox in #7238
- ci: publish Cloud Hypervisor test artifacts as release assets by @lpcox in #7247
- Create the /usr/local/bin/copilot entry in the agent chroot when it is missing by @lpcox with @Copilot in #7245
- Preserve a writable /host$HOME under arc-dind sysroot staging by @lpcox with @Copilot in #7244
- Upgrade gh-aw to v0.86.2 (pre-release) and recompile all workflows by @lpcox in #7277
- Align AWF enclave configuration with gh-aw keyed-array frontmatter by @lpcox with @Copilot in #7243
- Update B17 knowledge-base entry: reachability-aware DNS filtering (PR #7188) by @lpcox with @Copilot in #7261
- docs: sync schemas and specs with source changes by @github-actions[bot] in #7270
- Fix stale Cloud Hypervisor and enclave test assertions by @lpcox in #7291
- chore: update model-to-API mapping (2026-08-12) by @github-actions[bot] in #7271
- feat: add Cloud Hypervisor build smoke test by @lpcox in #7299
New Contributors
- @davidslater made their first contribution in #6996
Full Changelog: v0.27.44...v0.28.0
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
--container-runtime <runtime> Container runtime for the agent container.
"gvisor" — OCI runtime via Docker Compose (translates to runsc).
"sbx" — Docker sbx microVM with hypervisor isolation.
"firecracker" — explicit Linux/KVM Firecracker v1.16.1 preview.
"cloud-hypervisor" — explicit GitHub-hosted Ubuntu x86_64 KVM
Cloud Hypervisor v53.0 preview.
Unknown values are passed through as raw Docker runtime names.
Firecracker Preview:
--firecracker-preview Enable the Firecracker v1.16.1 workload-execution preview.
Requires Linux/KVM, local Docker, jailer, and pinned guest artifacts. (default: false)
--firecracker-binary <path> Path to the Firecracker v1.16.1 binary.
--firecracker-jailer-binary <path> Path to the matching Firecracker v1.16.1 jailer binary.
--firecracker-kernel <path> Path to the guest Linux kernel image.
--firecracker-rootfs <path> Path to the guest root filesystem image.
--firecracker-supervisor <path> Path to the built AWF Firecracker guest supervisor.
--firecracker-vcpus <count> Guest virtual CPU count (default: 2).
--firecracker-memory-mib <mib> Guest memory in MiB (default: 512).
--firecracker-api-timeout-ms <ms> Bounded API socket readiness timeout in milliseconds (default: 5000).
--firecracker-binary-sha256 <digest> Expected SHA-256 digest of the Firecracker binary.
--firecracker-jailer-sha256 <digest> Expected SHA-256 digest of the jailer binary.
--firecracker-kernel-sha256 <digest> Expected SHA-256 digest of the guest kernel.
--firecracker-rootfs-sha256 <digest> Expected SHA-256 digest of the guest rootfs.
--firecracker-supervisor-sha256 <digest> Expected SHA-256 digest of the AWF guest supervisor.
Cloud Hypervisor Preview (GitHub-hosted Ubuntu x86_64 KVM only):
--cloud-hypervisor-preview Enable the Cloud Hypervisor v53.0 workload-execution preview.
GitHub-hosted Ubuntu x86_64 KVM runners only. Requires local Docker
and pinned guest artifacts. (default: false)
--cloud-hypervisor-binary <path> Path to the Cloud Hypervisor v53.0 binary.
--cloud-hypervisor-kernel <path> Path to the PCI-capable guest Linux kernel image.
--cloud-hypervisor-rootfs <path> Path to the guest root filesystem image.
--cloud-hypervisor-supervisor <path> Path to the built AWF guest supervisor (shared with Firecracker).
--cloud-hypervisor-vcpus <count> Guest virtual CPU count (default: 2).
--cloud-hypervisor-memory-mib <mib> Guest memory in MiB (default: 512).
--cloud-hypervisor-api-timeout-ms <ms> Bounded API socket readiness timeout in milliseconds (default: 5000).
--cloud-hypervisor-binary-sha256 <digest> Expected SHA-256 digest of the Cloud Hypervisor binary.
--cloud-hypervisor-kernel-sha256 <digest> Expected SHA-256 digest of the guest kernel.
--cloud-hypervisor-rootfs-sha256 <digest> Expected SHA-256 digest of the guest rootfs.
--cloud-hypervisor-supervisor-sha256 <digest>
Expected SHA-256 digest of the AWF guest supervisor.
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--pids-limit <limit> Process/thread ceiling for the agent container (e.g., 1000, 2000). Default: 1000 (default: "1000")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--network-isolation Enforce egress via Docker network topology (internal network +
dual-homed proxy) instead of iptables. Requires no sudo/NET_ADMIN.
Not yet supported with --dns-over-https or --enable-host-access.
Enabled by default (strict security).
--no-network-isolation Disable network-isolation mode (requires --legacy-security).
--topology-attach <name> With --network-isolation, attach an externally-launched trusted container
(by name) to the internal network so the agent can reach it.
Repeatable. Example: --topology-attach mcp-gateway --topology-attach difc-proxy (default: [])
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 grants SSH access to the host.
Example: 5432,6379
--enable-dind Enable Docker-in-Docker by exposing host Docker socket.
WARNING: allows firewall bypass via docker run (default: false)
--legacy-security Enable legacy security mode (sudo, host-access, iptables).
Default behavior is strict security (network-isolation + api-proxy).
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--copilot-api-target <host> Target hostname for Copilot API requests (default: api.githubcopilot.com)
--openai-api-target <host> Target hostname for OpenAI API requests (default: api.openai.com)
--openai-api-base-path <path> Base path prefix for OpenAI API requests (e.g. /serving-endpoints for Databricks)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--anthropic-api-base-path <path> Base path prefix for Anthropic API requests (e.g. /anthropic)
--openai-api-auth-header <name> Custom auth header name for OpenAI requests (default: Authorization with Bearer prefix)
--anthropic-api-auth-header <name> Custom auth header name for Anthropic requests (default: x-api-key)
--gemini-api-target <host> Target hostname for Gemini API requests (default: generativelanguage.googleapis.com)
--gemini-api-base-path <path> Base path prefix for Gemini API requests
--vertex-api-target <host> Target hostname for Vertex API requests (default: aiplatform.googleapis.com)
--vertex-api-base-path <path> Base path prefix for Vertex API requests
--anthropic-auto-cache Enable Anthropic prompt-cache optimizations in the API proxy (requires --enable-api-proxy).
Injects cache breakpoints on tools/system/messages, upgrades TTL to 1h,
and strips ANSI codes — typically saves ~90% on Anthropic API input costs. (default: false)
--anthropic-cache-tail-ttl <5m|1h> TTL for the rolling-tail cache breakpoint when --anthropic-auto-cache is enabled.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> Max request bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
--max-model-multiplier <model:multiplier,...>
Per-model cost multipliers for effective token accounting (requires --enable-api-proxy).
Format: comma-separated model:multiplier pairs, e.g.
claude-opus-4-5-1m:10,claude-opus-4-5-200k:2.5
Multipliers must be positive numbers. Models without
a multiplier default to 1×.
--max-model-multiplier-cap <number> Maximum allowed model cost multiplier (requires --enable-api-proxy).
Requests for models whose resolved multiplier exceeds this cap
are rejected with HTTP 400 and error type model_multiplier_cap_exceeded.
Must be a positive number.
--max-permission-denied <number> Maximum number of upstream 401/403 responses allowed per run (requires --enable-api-proxy).
When reached, the API proxy rejects all subsequent requests with HTTP 403
and error type permission_denied_limit_exceeded, stopping the run to avoid
wasting tokens on misconfigured credentials.
Must be a positive integer.
--max-cache-misses <number> Maximum consecutive cache misses allowed per run (requires --enable-api-proxy).
A miss counts only when input_tokens > 0 and cache_read_tokens === 0.
Responses with cache_read_tokens > 0 reset the miss streak.
Must be a positive integer.
--enable-token-steering Enable effective token budget steering in the API proxy (requires --enable-api-proxy).
Injects budget-warning system messages at 80%, 90%, 95%, and 99%
usage to nudge the agent to wrap up before hitting the hard limit. (default: false)
--difc-proxy-host <host:port> Connect to an external DIFC proxy (mcpg) at host:port.
Enables the CLI proxy sidecar that routes gh commands through the DIFC proxy.
The DIFC proxy must be started externally (e.g., by the gh-aw compiler).
--difc-proxy-ca-cert <path> Path to TLS CA cert written by the external DIFC proxy.
Recommended when --difc-proxy-host is set for TLS verification.
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1786577067586")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
--session-state-dir <path> Directory to save Copilot CLI session state (events.jsonl, session data)
--diagnostic-logs Collect container logs, exit state, and sanitized config on non-zero exit.
Useful for debugging container startup failures (e.g. Squid crashes in DinD).
Written to <workDir>/diagnostics/ (or <audit-dir>/diagnostics/ when set). (default: false)
--reflect Start AWF, query the API proxy /reflect endpoint, and print its JSON response (default: false)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.28.0/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.28.0ghcr.io/github/gh-aw-firewall/agent:0.28.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.28.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
davidslater and lpcox