Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.25.53
What's Changed
Documentation
- [docs] Add model fallback feature documentation by @github-actions[bot] in #3617
Other Changes
- [Test Coverage] Add comprehensive test coverage for github-env and copilot-api-resolver by @github-actions[bot] in #3620
- fix(claude-token-optimizer): resolve workflow file via .lock.yml when .md lacks name field by @Copilot in #3633
- Refactor agent environment assembly into focused modules by @Copilot in #3636
- Refactor agent volume assembly into focused mount modules by @Copilot in #3638
- Refactor Squid config generation into focused modules by @Copilot in #3637
- Retry Anthropic requests after deprecated
anthropic-betaheader rejection by @Copilot in #3657
Full Changelog: v0.25.52...v0.25.53
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)
--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
--enable-opencode Enable OpenCode API proxy listener on port 10004 (requires --enable-api-proxy).
Only start this when the workflow uses the OpenCode engine. (default: false)
--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-cach...
Release v0.25.52
What's Changed
Other Changes
- docs(spec): add port information to /reflect endpoint sections by @lpcox in #3561
- Remove dead host-path helper re-exports from agent-volumes by @Copilot in #3563
- Refactor Docker Compose teardown into a shared helper by @Copilot in #3564
- Refactor token usage record/metrics construction into shared token-persistence helpers by @Copilot in #3566
- Extract shared positive-integer parsing for api-proxy guards by @Copilot in #3565
- Sync source AWF schema copy with documented schema by @Copilot in #3567
- Remove unused
exportfromProbeResultinterface by @Copilot in #3584 - fix: upgrade test-coverage-improver sandbox to AWF v0.25.51 by @Copilot in #3583
- Stabilize test-coverage-reporter by isolating main-action unit tests from DinD probing by @Copilot in #3595
- api-proxy: fallback unavailable
gpt-5.xrequests to highest available family model by @Copilot in #3602 - feat(api-proxy): add middle-power model fallback with stale-cache recovery by @Copilot in #3607
Full Changelog: v0.25.51...v0.25.52
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)
--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
--enable-opencode Enable OpenCode API proxy listener on port 10004 (requires --enable-api-proxy).
...
Contributors
lpcox
Assets 14
Release v0.25.51
What's Changed
Documentation
- [docs] docs: sync OTEL attribute names and environment variable references by @github-actions[bot] in #3512
Other Changes
- [Test Coverage] Improve coverage for main-action and preflight uncovered branches by @github-actions[bot] in #3515
- Reduce
test-coverage-improvertoken burn by narrowing file access and preloading target sources by @Copilot in #3521 - Optimize Smoke Claude workflow token footprint by removing Playwright and constraining turns by @Copilot in #3522
- fix(squid): chown bind-mounted log dirs to proxy user on startup by @salmanmkc in #3532
- Narrow
log-discoveryAPI: makeisContainerRunningtest-helper only by @Copilot in #3530 - docs: credential exclusion requires apiProxy.enabled by @lpcox in #3550
- feat: auto-detect DinD split filesystem via sentinel probe by @lpcox in #3554
- fix(dind-probe): address review feedback from #3554 by @lpcox in #3556
- Support self-hosted runner toolcache in chroot PATH resolution by @Copilot in #3545
Full Changelog: v0.25.50...v0.25.51
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)
--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
--enable-opencode Enable OpenCode API proxy listener on port 10004 (requires --enable-api-proxy).
Only start this when the workflow uses the ...
Contributors
lpcox and salmanmkc
Assets 14
Release v0.25.50
What's Changed
Other Changes
- chore: recompile all workflow lock files by @lpcox in #3345
- refactor: split token-tracker.js into four focused modules by @Copilot in #3343
- Make
BuildConfigInputsinternal tobuild-configby @Copilot in #3358 - Refactor iptables/ip6tables chain teardown into shared helper by @Copilot in #3359
- Deduplicate AWF_TOKEN_LOG_DIR setup across token-tracker tests by @Copilot in #3360
- Refactor container cleanup to deduplicate log/session preservation paths by @Copilot in #3361
- fix: add resilient gh-aw installer and --ignore-scripts to lock files by @lpcox in #3363
- fix: revert --ignore-scripts for Claude Code (needs postinstall) by @lpcox in #3371
- Narrow container-lifecycle API by moving kill-state helpers to test-only export by @Copilot in #3372
- Narrow rules API surface by making
mergeRuleSetsinternal by @Copilot in #3373 - chore: recompile workflows after --ignore-scripts revert by @lpcox in #3378
- Make
resolveImagesmodule-private inpredownloadand align tests to public API by @Copilot in #3384 - Narrow
domain-utilsAPI by privatizing agent-image helper exports by @Copilot in #3385 - Privatize ruleset internals and test rules parsing through public API by @Copilot in #3395
- Internalize
DOMAIN_CHAR_PATTERNand decouple tests from non-API regex internals by @Copilot in #3396 - fix: switch doc-maintainer from copilot to claude engine by @lpcox in #3414
- refactor: unexport internal helpers in copilot-api-resolver by @Copilot in #3394
- Make
DLP_PATTERNSinternal and decouple tests from module internals by @Copilot in #3398 - [Test Coverage] Improve host-iptables-shared branch coverage by @github-actions[bot] in #3403
- Optimize export-audit workflow token usage by precomputing data and reducing verification/search fanout by @Copilot in #3411
- Optimize Security Guard workflow token usage and reduce runaway turn cost by @Copilot in #3412
- Refactor option parser facade to direct re-exports and unify flag validation type by @Copilot in #3428
- Remove dead host-path-prefix re-exports from
agent-volumesby @Copilot in #3425 - Prune dead
host-envcompatibility re-exports after module split by @Copilot in #3426 - tests: replace host-env barrel imports with canonical host-env split modules by @Copilot in #3427
- Fail fast in chroot mode on Alpine/musl daemon hosts and document glibc requirements by @Copilot in #3397
- Refactor api-proxy startup to adapter-only validation/model discovery paths by @Copilot in #3444
- Align log discovery with canonical Squid container constant by @Copilot in #3445
- Refactor duplicated host-service port allowance loops in setup-iptables by @Copilot in #3443
- [Test Coverage] Add test coverage for build-config and predownload commands by @github-actions[bot] in #3455
- Optimize Security Guard workflow cost profile (Sonnet 4.5, 3-turn cap, early noop gate) by @Copilot in #3461
- feat: add OpenTelemetry distributed tracing to api-proxy sidecar by @Copilot in #3470
- feat: Add smoke-otel-tracing workflow for api-proxy OTEL validation by @lpcox in #3475
- fix: Use --build-local in smoke-otel-tracing for latest api-proxy code by @lpcox in #3483
- fix: align OTEL attributes with gen_ai semconv spec by @lpcox in #3488
- refactor: split validate-options.ts into focused validator modules by @Copilot in #3479
- refactor: deduplicate SSL-Bump fixture in squid-config-security tests by @Copilot in #3480
- refactor(tests): extract makeMockExecaProcess helper in log-streamer.test.ts by @Copilot in #3482
- fix: flatten OTEL cache attribute names for Sentry compatibility by @lpcox in #3492
- fix: use awf.usage namespace for cache/reasoning OTEL attributes by @lpcox in #3495
- refactor: split anthropic-transforms.js into focused sub-modules by @Copilot in #3478
- refactor: extract useCleanupTestDir to eliminate repeated test boilerplate by @Copilot in #3481
- fix: use Sentry measurement naming for cache token attributes by @lpcox in #3498
- fix: emit cache token OTEL attributes as strings for Sentry by @lpcox in #3501
- fix: rename OTEL cache attrs to avoid Sentry PII scrubber by @lpcox in #3504
- docs: add OTEL Sentry attribute reference by @lpcox in #3508
Full Changelog: v0.25.49...v0.25.50
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 ...
Contributors
lpcox
Assets 14
Release v0.25.49
What's Changed
Other Changes
- [Test Coverage] Add branch-coverage tests for container-cleanup.ts by @github-actions[bot] in #3316
- Optimize Smoke Claude workflow token footprint and turn budget by @Copilot in #3321
- Harden Copilot proxy auth normalization to avoid malformed Authorization headers by @Copilot in #3322
- Refactor COPILOT_MODEL resolution to remove duplicated env precedence logic by @Copilot in #3325
- refactor: extract shared service test imports into service-test-setup.test-utils by @Copilot in #3324
- Refactor proxy request error path into shared handler by @Copilot in #3323
Full Changelog: v0.25.48...v0.25.49
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)
--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
--enable-opencode Enable OpenCode API proxy listener on port 10004 (requires --enable-api-proxy).
Only start this when the workflow uses the OpenCode engine. (default: false)
--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.
...
Release v0.25.48
What's Changed
Other Changes
- Optimize export-audit workflow token usage by precomputing audits and bounding verification by @Copilot in #3258
- Harden gh-aw installation in agentic workflow lock files by @Copilot in #3260
- fix: handle grep no-match exit in claude-token-optimizer step by @Copilot in #3261
- refactor: split
src/host-env.tsinto focused modules by @Copilot in #3259 - fix: remove unused exports from public API surface (batch 2) by @lpcox in #3265
- refactor: extract addDnsRules helper to eliminate duplicate DNS iptables rule pairs by @Copilot in #3273
- refactor(api-proxy): deduplicate null tool_call type normalization by @Copilot in #3272
- refactor(services): deduplicate container security-hardening config across sidecar builders by @Copilot in #3274
- chore: run test coverage improver twice daily by @lpcox in #3280
- chore: recompile test-coverage-improver lock file by @lpcox in #3287
- [Test Coverage] Add test coverage for subcommands and main-action by @github-actions[bot] in #3288
- Optimize
test-coverage-improverprompt caching and run cadence by @Copilot in #3298 - refactor: split api-proxy-service.test.ts into focused test modules by @Copilot in #3299
- fix: postprocess claude-token-optimizer lock file to use local awf build by @Copilot in #3300
- fix: resolve test failures on macOS by @lpcox in #3304
Full Changelog: v0.25.47...v0.25.48
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....
Contributors
lpcox
Assets 14
Release v0.25.47
What's Changed
Other Changes
- Refactor OIDC provider tests to share base mock server helper by @Copilot in #3138
- Refactor audit-enricher tests to centralize default policy manifest fixture by @Copilot in #3139
- refactor(tests): extract setupDefaultIptablesMocks to eliminate repeated iptables mock sequences by @Copilot in #3140
- refactor: delete dead-code duplicate src/types/config.ts by @Copilot in #3141
- Refactor log command tests to centralize empty-stats harness setup by @Copilot in #3142
- Remove dead re-export barrel
src/types/config.tsby @Copilot in #3144 - fix(entrypoint): preserve setup-* PATH ordering in fallback hostedtoolcache scan by @Copilot in #3143
- fix: remove dead re-exports of WrapperConfig component types by @lpcox in #3161
- Refactor API proxy request path into focused guard and transport modules by @Copilot in #3159
- Refactor option parser utilities into domain-focused modules with compatibility wrappers by @Copilot in #3160
- Fix token usage extraction for OpenAI Responses API (
response.usage) in SSE/WS paths by @Copilot in #3178 - fix(api-proxy): route GPT-5 family models to /responses regardless of auth path by @Copilot in #3177
- feat: auto-forward OTEL_* env vars with one-shot token protection for headers by @Copilot in #3180
- refactor: [Export Audit] Remove test-only re-exports from barrel modules by @lpcox in #3169
- Cap
/reflecteffective-token totals at configuredmaxEffectiveTokensby @Copilot in #3208 - Refactor api-proxy SIGTERM/SIGINT shutdown flow into a shared handler by @Copilot in #3209
- fix(docker): apply docker-host-path-prefix to all compose service mounts by @salmanmkc in #3218
- Refactor service tests to share temp workDir lifecycle setup by @Copilot in #3204
- Optimize Documentation Maintainer token usage and prompt/cache behavior by @Copilot in #3202
- Deduplicate provider adapter host/basePath/validation methods in shared adapter factory by @Copilot in #3210
- Remove unused
wrapper-configsub-interface exports from public type surface by @Copilot in #3211 - fix(api-proxy): gpt-5.4-mini routed to /chat/completions instead of /responses by @Copilot in #3212
- fix: handle cache-memory cold start in issue duplication detector by @lpcox in #3215
- docs: expand README to reflect AWF feature scope and command surface by @Copilot in #3214
- fix(api-proxy): apply responses wire API unconditionally for GPT-5/O3 models on COPILOT_GITHUB_TOKEN path by @Copilot in #3207
- fix: clean up remaining export audit issues by @lpcox in #3230
- refactor: split main-action.ts into validate-options and build-config modules by @Copilot in #3229
- Codex: remove
openai-proxyenv_keyrequirement in postprocessed lock workflows by @Copilot in #3234 - fix: use gh CLI for reliable API access in issue duplication detector by @lpcox in #3235
- Refactor Azure OIDC provider to inherit shared token lifecycle from BaseOidcTokenProvider by @Copilot in #3243
- [awf] Support Azure Copilot BYOK env routing in api-proxy and resolve gpt-5.4 via gpt-5 family aliases by @Copilot in #3241
Full Changelog: v0.25.46...v0.25.47
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 Co...
Contributors
lpcox and salmanmkc
Assets 14
Release v0.25.46
What's Changed
Other Changes
Full Changelog: v0.25.45...v0.25.46
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)
--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
--enable-opencode Enable OpenCode API proxy listener on port 10004 (requires --enable-api-proxy).
Only start this when the workflow uses the OpenCode engine. (default: false)
--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 to...
Contributors
lpcox
Assets 14
Release v0.25.44
What's Changed
Documentation
- [docs] Add --anthropic-auto-cache and --anthropic-cache-tail-ttl documentation by @github-actions[bot] in #2881
- [docs] docs: document Squid allow_api_proxy_ip ACL and Gemini raw-IP fix by @github-actions[bot] in #3009
Other Changes
- refactor: split src/cli.ts into focused modules by @Copilot in #2900
- refactor(stats-formatter): make format-specific functions module-private by @Copilot in #2889
- refactor(api-proxy): dedupe Azure OIDC helpers via shared github-oidc module by @Copilot in #2887
- Harden gh-aw extension install in CI/CD gaps assessment workflow by @Copilot in #2904
- Refactor option parser tests into domain-focused suites by @Copilot in #2902
- fix(export-audit): fix false-positive unused-export detection for multi-line imports by @Copilot in #2888
- refactor: split agent-environment.test.ts into 4 focused test modules by @Copilot in #2903
- Harden pid-tracker API surface by removing internal helper exports by @Copilot in #2890
- fix(logs): restrict stats formatter public API to
formatStatsby @Copilot in #2891 - refactor(types): split config.ts into focused modules and compose WrapperConfig by domain by @Copilot in #2899
- Remove dead
mockLoggerexport from logger test helper by @Copilot in #2892 - Hide internal CLI exports from the public entry point by @Copilot in #2894
- refactor: remove duplicate HTTP helpers from OidcTokenProvider by @Copilot in #2898
- fix(api-proxy): add missing JS modules to Dockerfile COPY by @lpcox in #2950
- refactor: reduce pid-tracker API surface and harden api-proxy startup retry handling by @Copilot in #2895
- test: remove dead
mockLoggerexport from logger test helper by @Copilot in #2897 - Refactor host iptables tests and fix follow-up CI regressions by @Copilot in #2901
- refactor: remove dead exports from export audit by @lpcox in #2960
- fix: add --ignore-scripts to security-guard Claude Code install by @lpcox in #2963
- refactor: split server.test.js into focused test files by @Copilot in #2969
- refactor: split token-tracker test file for maintainability by @Copilot in #2970
- refactor: fix test import path inconsistency for docker-manager by @Copilot in #2975
- refactor: remove dead re-exports from cli.ts and unexport ExecaMockResult by @lpcox in #2992
- fix: unblock Smoke Gemini — exclude MCP host env leak, allow api-proxy IP through Squid by @Copilot in #2986
- feat: --max-model-multiplier CLI flag + token steering body injection by @Copilot in #3004
- refactor: extract writeConfigs into dedicated config-writer module by @Copilot in #3031
- Refactor API proxy adapters to share structural startup methods by @Copilot in #3027
- refactor: split main-action.ts into preflight, network-setup, and signal-handler modules by @Copilot in #3029
- Refactor host iptables into focused modules with a stable public facade by @Copilot in #3030
- Refactor AWS/GCP OIDC providers to share lifecycle orchestration by @Copilot in #3026
- Refactor squid config generation into focused modules by @Copilot in #3028
- feat: gate token steering behind opt-in flag, adjust thresholds to 80/90/95/99% by @Copilot in #3039
Full Changelog: v0.25.43...v0.25.44
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> ...
Contributors
lpcox
Assets 14
Release v0.25.43
What's Changed
Documentation
- [docs] Documentation Sync - May 10, 2026 by @github-actions[bot] in #2824
Other Changes
- fix(deps): patch high-severity vulnerabilities in babel and fast-uri by @lpcox in #2799
- refactor: remove dead re-exports from providers/index.js by @lpcox in #2800
- refactor: extract shared OIDC refresh/sleep utilities by @lpcox in #2811
- feat(api-proxy): enforce absolute maximum LLM invocation count per run by @Copilot in #2798
- refactor: extract shared SSL Bump fixture in squid-config tests by @lpcox in #2812
- refactor: extract shared logger mock factory to test-utils by @lpcox in #2814
- fix: unexport test-only command option types by @lpcox in #2819
- [Test Coverage] Improve host-iptables.ts branch coverage by @github-actions[bot] in #2829
- api-proxy: set
COPILOT_PROVIDER_WIRE_API=responsesfor GPT-5-family Copilot BYOK runs by @Copilot in #2842 - Restore
--ignore-scriptsfor engine CLI installs in lock files, add regression guard, install Claude native binary explicitly, and harden Smoke Codex safe-output targeting by @Copilot in #2840 - Honor Unix DOCKER_HOST sockets for DinD mounts on ARC runners by @Copilot in #2841
- Fix chroot bind mounts for ARC/DinD split runner-daemon filesystems by @Copilot in #2843
- Add first-class ARC/DinD compatibility mode for AWF by @Copilot in #2839
Full Changelog: v0.25.42...v0.25.43
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> ...
Contributors
lpcox