Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.25.13
What's Changed
Other Changes
- feat: add Daily Claude Token Usage Analyzer workflow by @lpcox in #1605
- fix: prevent Squid config injection via --allow-domains and --allow-urls by @Mossaka in #1517
- perf: reduce smoke-copilot token usage with pre-steps and tool trimming by @lpcox in #1613
Full Changelog: v0.25.12...v0.25.13
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775156154038")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
--session-state-dir <path> Directory to save Copilot CLI session state (events.jsonl, session data)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.13/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.13/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.13/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.13/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.13/awf-da...Contributors
Mossaka and lpcox
Assets 9
Release v0.25.12
What's Changed
Other Changes
Full Changelog: v0.25.11...v0.25.12
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775148149950")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
--session-state-dir <path> Directory to save Copilot CLI session state (events.jsonl, session data)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.12/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.12/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.12/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.12/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.12/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.12/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL h...Contributors
lpcox
Assets 9
Release v0.25.11
What's Changed
Other Changes
- fix: rename and scope token analyzer to Copilot workflows by @lpcox in #1588
- fix: capture full session state — replace blanket ~/.copilot mount, add --session-state-dir by @lpcox in #1593
Full Changelog: v0.25.10...v0.25.11
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775104890864")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
--session-state-dir <path> Directory to save Copilot CLI session state (events.jsonl, session data)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.11/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.11/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.11/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.11/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.11/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.11/checksums.txt -o chec...Contributors
lpcox
Assets 9
Release v0.25.10
What's Changed
Other Changes
- feat: add daily token usage analyzer workflow by @lpcox in #1557
- fix: recompile token-usage-analyzer lock file by @lpcox in #1586
- feat: add esbuild single-file bundle as lightweight distribution by @Mossaka in #1581
Full Changelog: v0.25.9...v0.25.10
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775088436076")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.10/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.10/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.10/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.10/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.10/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.10/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-...Contributors
Mossaka and lpcox
Assets 9
Release v0.25.9
What's Changed
Other Changes
- fix: copy AWF CA cert to chroot-accessible path for ssl-bump by @lpcox in #1555
- feat: auto-detect host DNS resolvers instead of hardcoding Google DNS by @Mossaka in #1513
- [Test Coverage] Add 100% test coverage for logs-audit command by @github-actions[bot] in #1411
Full Changelog: v0.25.8...v0.25.9
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775077715805")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.9/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.9/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.9/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.9/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.9/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.9/checksums.txt -o checksums.tx...Contributors
Mossaka and lpcox
Assets 8
Release v0.25.8
What's Changed
Other Changes
Full Changelog: v0.25.7...v0.25.8
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775068541233")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.8/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.8/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.8/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.8/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.8/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.8/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.8/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/d...Contributors
lpcox
Assets 8
Release v0.25.7
What's Changed
Other Changes
Full Changelog: v0.25.6...v0.25.7
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775060692330")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.7/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.7/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.7/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.7/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.7/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.7/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.7/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/d...Contributors
lpcox
Assets 8
Release v0.25.6
What's Changed
Other Changes
- fix: api-proxy auth chain — trim keys, align placeholder format, add diagnostics by @lpcox in #1528
- feat: add smoke-services workflow for --allow-host-service-ports e2e testing by @lpcox in #1534
- feat: add token usage tracking to api-proxy sidecar by @lpcox in #1539
- fix: disable IPv6 in agent container to prevent squid proxy bypass by @lpcox in #1544
Full Changelog: v0.25.5...v0.25.6
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1775017022629")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.6/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.6/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.6/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.6/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.6/awf...Contributors
lpcox
Assets 8
Release v0.25.5
What's Changed
Other Changes
Full Changelog: v0.25.4...v0.25.5
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1774935821294")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.5/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.5/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.5/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.5/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.5/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.5/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.5/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/...Contributors
lpcox
Assets 8
Release v0.25.4
What's Changed
Other Changes
- fix: always derive GH_HOST from GITHUB_SERVER_URL to prevent proxy leakage by @lpcox in #1493
- fix: debug logging for GITHUB_PATH merge + document setup-* tool availability in chroot by @Copilot in #1468
- feat: add volume mount for ~/.copilot/session-state to persist events.jsonl by @Copilot in #1469
Full Changelog: v0.25.3...v0.25.4
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.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 both squid and agent images)
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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)
--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)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1774840816828")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.4/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.4/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.4/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.4/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.4/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.4/che...Contributors
lpcox