Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release list
Release v0.27.30
What's Changed
Other Changes
- chore: upgrade gh-aw to v0.82.7 pre-release, recompile by @lpcox in #6088
- [Test Coverage] Branch coverage gaps: signal-handler, preflight, compose-generator, compose-network by @github-actions[bot] in #6085
- feat: add gVisor smoke test workflow by @lpcox in #6092
- feat: optimize config-consistency-auditor — early exit, trimmed toolset, leaner prompt by @lpcox with @Copilot in #6087
- chore: recompile workflows after #6087 by @lpcox in #6096
- feat: add smoke-docker-sbx workflow by @lpcox in #6099
- feat: gVisor runtime support by @lpcox in #6093
- Fix intermittent api-proxy token telemetry loss on fast shutdown by @lpcox with @Copilot in #6105
- chore: upgrade gh-aw extension to v0.82.8 (pre-release) by @lpcox in #6116
- chore: update model-to-API mapping (2026-07-11) by @github-actions[bot] in #6110
- [Test Coverage] host-iptables-validation.ts by @github-actions[bot] in #6113
- chore(deps): bump eslint to 10.7.0 and @types/node to 25.9.5 by @lpcox with @Copilot in #6119
- docs: update runner doctor catalog — D1 gVisor resolved, add B11 silent repair exit-1 by @lpcox with @Copilot in #6118
- feat: add Docker sbx microVM runtime support by @lpcox in #6101
Full Changelog: v0.27.29...v0.27.30
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.
Unknown values are passed through as raw Docker runtime names.
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")
--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 Experimental: 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. (default: false)
--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)
--...
Contributors
lpcox
Assets 14
- 2.28 KB
2026-07-12T00:18:12Z - 678 KB
2026-07-12T00:18:12Z - 39.9 KB
2026-07-12T00:18:12Z - 39.9 KB
2026-07-12T00:18:12Z - 51.2 MB
2026-07-12T00:18:12Z - 58.3 MB
2026-07-12T00:18:12Z - 49.8 MB
2026-07-12T00:18:12Z - 53.5 MB
2026-07-12T00:18:12Z - 2.96 MB
2026-07-12T00:18:12Z - 916 Bytes
2026-07-12T00:18:12Z -
2026-07-12T00:08:09Z -
2026-07-12T00:08:09Z - Loading
Release v0.27.29
What's Changed
Other Changes
- feat: recursive alias resolution with cycle protection in validateRequestedModel by @pelikhan with @Copilot in #6054
- chore: upgrade gh-aw to v0.82.7 pre-release and recompile workflows by @lpcox in #6064
- [Test Coverage] Add branch coverage for diagnostic-collector, docker-socket, hosts-file by @github-actions[bot] in #6060
- chore: update model-to-API mapping (2026-07-09) by @github-actions[bot] in #6055
- refactor: pre-validate host port specs once in TypeScript, eliminate duplicate shell parser by @lpcox with @Copilot in #6067
- chore: upgrade gh-aw to v0.82.7 pre-release and recompile workflows by @lpcox in #6071
- fix: log stderr from rootless permission repair and make chroot-home removal non-fatal by @lpcox in #6072
- docs: add B10 to runner doctor catalog (rootless perm-repair tag@digest timeout) by @lpcox with @Copilot in #6078
Full Changelog: v0.27.28...v0.27.29
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 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")
--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 Experimental: 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. (default: false)
--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)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--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 ...
Contributors
pelikhan and lpcox
Assets 14
Release v0.27.28
What's Changed
Other Changes
- docs: sync schemas and specs with source changes by @github-actions[bot] in #6014
- [Test Coverage] Add branch-coverage tests for log-aggregator, squid/config-sections, ssl-bump, pid-tracker by @github-actions[bot] in #6020
- chore: upgrade gh-aw extension to v0.82.5 pre-release by @lpcox in #6022
- fix: use tag-only image ref in rootless permission repair by @lpcox in #6025
- refactor: split config-assembly.ts validators into domain-specific modules by @lpcox with @Copilot in #6035
- refactor(api-proxy): collapse repeated OIDC header setup into
createProviderOidcHeaderStrategyby @lpcox with @Copilot in #6038 - refactor: split buildApiProxyBaseEnv into focused env-var builders by @lpcox with @Copilot in #6033
- chore(deps): bump typescript-eslint to 8.63.0 by @lpcox with @Copilot in #6042
- docs: mark A17 (build-tools digest pinning) as fixed by @lpcox with @Copilot in #6040
- refactor: split workdir-setup.ts into focused single-responsibility modules by @lpcox with @Copilot in #6034
- refactor: split coverage-improvements.test.ts into per-module test files by @lpcox with @Copilot in #6036
- refactor: consolidate shell port-spec parsing into shared parse_port_specs() by @lpcox with @Copilot in #6037
- Add CI guard to prevent SUPPORTED_COPILOT_MODELS drift from pricing catalog by @lpcox with @Copilot in #6039
- fix: validate COPILOT_MODEL after alias resolution, not before by @pelikhan with @Copilot in #6044
- fix: mock accessSync in workdir-setup test to avoid macOS false failure by @lpcox in #6050
Full Changelog: v0.27.27...v0.27.28
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 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")
--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 Experimental: 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. (default: false)
--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)
-...
Contributors
pelikhan and lpcox
Assets 14
Release v0.27.27
What's Changed
Other Changes
- [Test Coverage] config-writer, agent-options, host-env branch coverage by @github-actions[bot] in #5980
- chore: update model-to-API mapping (2026-07-07) by @github-actions[bot] in #5975
- Update Runner Doctor A15 status to reflect merged ARC/DinD permission-repair fix by @lpcox with @Copilot in #5971
- chore: upgrade gh-aw to v0.82.3 pre-release and recompile workflows by @lpcox in #5982
- fix: add diagnostic EACCES guard to workdir setup by @lpcox in #5984
- feat: add
build-toolsto SHA digest pinning infrastructure by @lpcox with @Copilot in #5986 - fix: propagate Vertex AI config fields to spec by @github-actions[bot] in #5990
- docs: Runner Doctor update — add failure modes A16, A17, B8, B9, C8; update B7, C3 lookup by @lpcox with @Copilot in #5992
- Refactor provider OIDC auth-header plumbing into a shared resolver by @lpcox with @Copilot in #5994
- Refactor cli-proxy server into auditable security, runner, and logging modules by @lpcox with @Copilot in #5995
- Add
claude-sonnet-5to AI-credits pricing to prevent runtime unknown-model rejection by @lpcox with @Copilot in #5993 - Refactor api-proxy request path into auditable header and upstream modules by @lpcox with @Copilot in #5996
- Unblock AI credits guard for Claude Fable/Mythos 5 by adding curated pricing and catalog fallback entries by @lpcox with @Copilot in #5997
- fix: harden token tracker against unsupported response encodings and WS fragmentation by @lpcox in #6003
- Clarify MCP localhost rewrite, transport semantics, and reachability under network isolation by @lpcox with @Copilot in #6005
- fix: add Gemini usageMetadata support to token parsers by @lpcox in #6008
Full Changelog: v0.27.26...v0.27.27
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 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")
--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 Experimental: 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. (default: false)
--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 ...
Contributors
lpcox
Assets 14
Release v0.27.26
What's Changed
Other Changes
Full Changelog: v0.27.25...v0.27.26
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 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")
--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 Experimental: 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. (default: false)
--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)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--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 ...
Contributors
lpcox
Assets 14
Release v0.27.25
What's Changed
Other Changes
- Upgrade gh-aw to v0.82.2 pre-release and recompile workflows by @lpcox in #5932
- chore: upgrade gh-aw to v0.82.2 pre-release and recompile workflows by @lpcox in #5946
- [Test Coverage] coverage-gaps.test.ts by @github-actions[bot] in #5941
- Deduplicate OIDC/static auth-header resolution across API proxy providers by @lpcox with @Copilot in #5944
- Refactor provider unconfigured-response handling into adapter-factory metadata by @lpcox with @Copilot in #5945
- fix(test): update BYOK workflow test to match recompiled lock files by @lpcox in #5950
- fix: handle EPERM when chmod'ing pre-existing mcp-logs directory by @lpcox in #5956
- fix: tolerate EROFS when chmod on pre-existing mcp-logs dir fails by @lpcox in #5960
Full Changelog: v0.27.24...v0.27.25
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 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")
--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 Experimental: 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. (default: false)
--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)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--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 heade...
Contributors
lpcox
Assets 14
Release v0.27.24
Full Changelog: v0.27.23...v0.27.24
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 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")
--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 Experimental: 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. (default: false)
--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)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--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 --an...
Release v0.27.22
What's Changed
Other Changes
Full Changelog: v0.27.21...v0.27.22
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 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")
--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 Experimental: 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. (default: false)
--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)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--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
--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.
...
Contributors
lpcox
Assets 14
Release v0.27.21
What's Changed
Documentation
- chore: update model-to-API mapping (2026-07-01) by @github-actions[bot] in #5742
Other Changes
- Refactor preflight allowed-domain resolution into explicit pipeline stages by @lpcox with @Copilot in #5757
- Refactor
startContainersinto focused startup and failure helpers by @lpcox with @Copilot in #5758 - fix: ensure chmod runs even when chown fails in rootless permission repair by @lpcox in #5766
- [Test Coverage] container-lifecycle missing branch coverage by @github-actions[bot] in #5743
- refactor(api-proxy): extract createProviderAuthScaffold to deduplicate provider adapter boilerplate by @lpcox with @Copilot in #5760
- Deduplicate
writeConfigsJest dependency mock registration across config-writer suites by @lpcox with @Copilot in #5761 - Refactor buildConfig by extracting API credential resolution by @lpcox with @Copilot in #5759
- feat: add
container.mountsto AWF config file schema by @lpcox with @Copilot in #5755 - Sync Copilot model allowlist with model API mapping by @lpcox with @Copilot in #5756
- docs: update runner doctor — A13 fixed in v0.27.15, B7 rootless repair incomplete by @lpcox with @Copilot in #5762
- refactor: split 309-line generateDockerCompose into focused phases by @lpcox with @Copilot in #5763
- Fix split-fs test to use actual effectiveHome instead of hardcoded /home by @lpcox in #5781
- chore: upgrade gh-aw to v0.82.1 pre-release and recompile workflows by @lpcox in #5748
- fix(ci): postprocess install-step swap must tolerate trailing --rootless flag by @lpcox in #5800
- fix: detect and expose system CA bundle for RHEL/Amazon Linux in chroot by @lpcox in #5783
Full Changelog: v0.27.20...v0.27.21
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 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")
--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 Experimental: 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. (default: false)
--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-...
Contributors
lpcox
Assets 14
Release v0.27.20
What's Changed
Other Changes
Full Changelog: v0.27.19...v0.27.20
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 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")
--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 Experimental: 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. (default: false)
--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)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--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
--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.
...
Contributors
lpcox