Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.27.2
What's Changed
Other Changes
- fix(api-proxy): use 'token' auth prefix for GHES enterprise Copilot API by @lpcox in #4755
- fix(api-proxy): stop double-counting cached tokens in AI credits by @lpcox in #4760
- fix: WIF/OIDC Anthropic auth regression — Squid blocks api-proxy OIDC exchange + ANTHROPIC_API_KEY leaks to agent by @Copilot in #4748
Full Changelog: v0.27.1...v0.27.2
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)
--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.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> Max request byt...
Contributors
lpcox
Assets 14
- 2.28 KB
2026-06-11T16:16:49Z - 618 KB
2026-06-11T16:16:49Z - 33.1 KB
2026-06-11T16:16:49Z - 33.1 KB
2026-06-11T16:16:50Z - 50.4 MB
2026-06-11T16:16:50Z - 57.4 MB
2026-06-11T16:16:50Z - 49.1 MB
2026-06-11T16:16:49Z - 52.7 MB
2026-06-11T16:16:49Z - 2.42 MB
2026-06-11T16:16:49Z - 916 Bytes
2026-06-11T16:16:49Z -
2026-06-11T16:06:40Z -
2026-06-11T16:06:40Z - Loading
Release v0.27.1
What's Changed
Other Changes
- fix: propagate config fields to all layers by @github-actions[bot] in #4671
- fix(ci): run AOAI api-key smoke pre-step in activation job so prompt step outputs resolve by @Copilot in #4540
- fix(cli-proxy): resolve IPv4/IPv6 readiness probe mismatch on dual-stack hosts by @Copilot in #4675
- feat: emit AI credits as OTEL span attributes by @lpcox in #4707
- chore: recompile all workflows with latest gh-aw by @lpcox in #4714
- feat: persist redacted resolved config as audit artifact by @lpcox in #4719
- fix: update workflow test SHA assertions after recompile by @lpcox in #4720
- Add opt-in diagnostics artifact for blocked LLM request bodies by @Copilot in #4678
Full Changelog: v0.27.0...v0.27.1
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)
--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 ...
Contributors
lpcox
Assets 14
Release v0.27.0
What's Changed
Other Changes
Full Changelog: v0.26.0...v0.27.0
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container 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)
--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.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> Max request bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
--max-model-multiplier <model:multiplier,...>
Per-model cost multipliers for effective token accountin...
Contributors
lpcox
Assets 14
Release v0.25.68
What's Changed
Other Changes
- refactor(tests): extract useTempDir helper, eliminate 9 duplicate temp-dir setup blocks by @Copilot in #4531
- feat(smoke-claude): token optimization — disable GitHub MCP, max-turns 2, single-turn bash by @Copilot in #4527
- fix(api-proxy): restore PAT-safe integration ID behavior and normalize dated CAPI model names by @Copilot in #4555
Full Changelog: v0.25.67...v0.25.68
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)
--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.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> ...
Release v0.25.67
What's Changed
Other Changes
- chore: suppress ts-prune false positives in host-iptables-test-setup.ts by @Copilot in #4524
- fix: forward GITHUB_COPILOT_INTEGRATION_ID to api-proxy as COPILOT_INTEGRATION_ID by @lpcox in #4416
- Narrow env-utils API by making
normalizeEnvValuemodule-local by @Copilot in #4526 - cli-proxy: fail-fast on DIFC proxy unavailability; add contribution-check workflow by @Copilot in #4529
- Remove unused exported type
CopilotModelValidationResultby @Copilot in #4525 - Extract computeTokenBudgetUsage to eliminate duplicated billing-critical log block by @Copilot in #4530
Full Changelog: v0.25.66...v0.25.67
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)
--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.25.66
What's Changed
Other Changes
- fix(api-proxy): add Azure/AWS/GCP OIDC support to Copilot adapter by @Copilot in #4407
- Fix Smoke Model Policy false failure from stale api-proxy log path by @Copilot in #4434
- Refactor api-proxy credential-forwarding tests into focused scenario files by @Copilot in #4441
- Refactor
proxyRequestguard enforcement into a shared pipeline by @Copilot in #4440 - Increase Security Guard turn budget and harden integration container build reliability by @Copilot in #4435
- Optimize
smoke-copilot-byoktoken cost via model right-sizing and prompt cacheability by @Copilot in #4439 - Reduce Documentation Maintainer token burn and improve run completion reliability by @Copilot in #4438
- Reduce Test Coverage Improver token usage by narrowing model/prompt/tool surface by @Copilot in #4437
- Increase Documentation Maintainer turn budget to prevent
error_max_turnsagent exits by @Copilot in #4436 - Deduplicate cloud OIDC provider initialization across Copilot and OpenAI adapters by @Copilot in #4458
- Refactor duplicated OIDC initialization-failure tests into shared helper by @Copilot in #4484
- [awf] cli-proxy: fail fast on external DIFC proxy unreachability by @Copilot in #4486
- fix(copilot-token-optimizer): reduce tool surface, increase timeout, redirect log artifacts by @Copilot in #4487
- Refactor host iptables tests to centralize Docker bridge gateway mocking and recompile Security Guard workflow by @Copilot in #4485
- feat: persist budget fields in token-usage.jsonl and align maxTurns/docs reporting by @lpcox in #4500
Full Changelog: v0.25.65...v0.25.66
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)
--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-...
Contributors
lpcox
Assets 14
Release v0.25.65
Full Changelog: v0.25.64...v0.25.65
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)
--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.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> Max request bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
--max-model-multiplier <model:multiplier,...>
Per-model cost multipliers for effective token accounting (requires --enable-api-proxy).
Format: comma-separated model:multiplier pairs, e.g.
...
Release v0.25.63
What's Changed
Other Changes
- [Test Coverage] cli-options and pid-tracker branch coverage by @github-actions[bot] in #4303
- fix(doc-maintainer): increase max-turns from 4 to 10 by @Copilot in #4315
- Narrow
resetAgentExternallyKilledto internal test helper surface by @Copilot in #4317 - Mark
validateAwfFileConfigas test-only internal export by @Copilot in #4318 - [awf] api-proxy: correctly capture Responses API cache reads in token usage rollups by @Copilot in #4311
- Add AWF config support for model-router provider settings by @Copilot in #4312
- [awf] Forward Copilot BYOK session metadata to upstream providers by @Copilot in #4314
- Validate and resolve
COPILOT_MODELaliases before engine launch by @Copilot in #4316
Full Changelog: v0.25.62...v0.25.63
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)
--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 ...
Release v0.25.60
Full Changelog: v0.25.59...v0.25.60
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)
--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.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> Max request bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
--max-model-multiplier <model:multiplier,...>
Per-model cost multipliers for effective token accounting (requires --enable-api-proxy).
Format: comma-separated model:multiplier pairs, e.g.
...
Release v0.25.58
What's Changed
Other Changes
- feat(api-proxy): pre-startup model validation via requestedModel config by @lpcox in #4025
- fix: synthesize identity files for ARC-DinD environments by @lpcox in #4026
- Refactor retry-logic tests to centralize shared HTTPS/stdout mocks by @Copilot in #4046
- Deduplicate env var setup/restore blocks in
agent-volumes-mountstests by @Copilot in #4048 - Deduplicate server test HTTPS_PROXY/module-reset bootstrap across split api-proxy tests by @Copilot in #4049
- Remove
copilotApiResolverTestHelpersfrom the production API surface by @Copilot in #4051 - Narrow host-path prefix API surface by @Copilot in #4052
- Remove test-only container lifecycle helper from production API surface by @Copilot in #4050
- refactor: split SquidConfig out of src/types/docker.ts into src/types/squid.ts by @Copilot in #4053
- Deduplicate
writeConfigstest setup inconfig-writer.test.tsby @Copilot in #4054 - Harden effective-token accounting for unknown and concrete model IDs by @Copilot in #4055
- fix: complete api-proxy config follow-ups and harden DinD identity synthesis by @lpcox in #4063
- fix: make DinD staging test platform-agnostic for identity synthesis by @lpcox in #4065
Full Changelog: v0.25.57...v0.25.58
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)
--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 (def...
Contributors
lpcox