Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.24.1
What's Changed
Other Changes
- ci: skip CI when only release.yml changes by @Mossaka in #1261
- docs: sync version references and add missing CLI flags by @Mossaka in #1223
- docs: document flag validation constraints by @Mossaka in #1230
- chore(deps): aggregated dependency updates by @Mossaka in #1218
- fix: use docker cp instead of file bind mounts for DinD compatibility by @Mossaka in #1079
- fix(proxy): add lowercase proxy vars and NODE_EXTRA_CA_CERTS by @Mossaka in #1234
- feat(cli): organize help text with logical option groups by @Mossaka in #1241
- test: add logger/aggregator tests for blocked domain detection by @Mossaka in #1262
- feat(cli): add --agent-timeout flag for execution time limit by @Mossaka in #1242
- feat(cli): add predownload command to pre-pull container images by @Mossaka in #1245
- feat(proxy): add GitHub Enterprise Cloud/Server support with automatic endpoint detection by @claude in #1264
Full Changelog: v0.24.0...v0.24.1
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
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)
--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)
-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., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--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")
--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
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)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--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-1773356466821")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
-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.24.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/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.24.1/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/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.24.1/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/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.24.1/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variab...Contributors
claude and Mossaka
Assets 8
Release v0.24.0
What's Changed
Other Changes
- test: add CI workflow for non-chroot integration tests by @Mossaka in #1048
- test: add DNS restriction enforcement tests by @Mossaka in #1054
- test: fix docker-warning tests and fragile timing dependencies by @Mossaka in #1049
- fix(ci): recompile ci-doctor and add missing workflows by @Copilot in #1067
- fix(deps): resolve high-severity rollup vulnerability in docs-site by @Copilot in #1069
- fix(deps): resolve minimatch ReDoS and ajv vulnerabilities by @Mossaka in #1152
- fix(squid): run Squid container as non-root user by @Mossaka in #1153
- fix(docker): disable IPv6 when ip6tables unavailable by @Mossaka in #1154
- fix(security): secure SSL Bump key wiping via tmpfs by @Mossaka in #1156
- fix(security): stop logging partial token values by @Mossaka in #1158
- fix(security): eliminate TOCTOU race conditions in ssl-bump.ts by @Mossaka in #1159
- fix(ci): resolve integration test suite failures on main by @Mossaka in #1151
- feat: combine all build-test workflows into single build-test.md by @Copilot in #1157
- fix(squid): block direct IP connections that bypass domain filtering by @Mossaka in #1160
- test: add workDir tmpfs hiding integration tests by @Mossaka in #1219
- test: add TOCTOU error path coverage for ssl-bump.ts by @Mossaka in #1161
- test: add chroot escape vector test coverage by @Mossaka in #1162
- test: add --proxy-logs-dir edge case coverage by @Mossaka in #1220
- test: add --allow-host-ports validation tests by @Mossaka in #1221
- test: add --skip-pull integration test by @Mossaka in #1222
- docs: clarify --image-tag behavior with agent-image presets by @Mossaka in #1228
- feat(cli): add short flags for frequently used options by @Mossaka in #1229
- fix(ci): update Copilot CLI version from 0.0.411 to 0.0.421 by @Mossaka in #1231
- fix(cli): clear LD_PRELOAD after one-shot-token library loads by @Mossaka in #1232
- test(docker): verify capsh execution chain after PR #715 by @Mossaka in #1240
- test: expand credential hiding tests to all 14 protected paths by @Mossaka in #1163
- feat(cli): add --memory-limit flag for configurable container memory by @Mossaka in #1243
- feat(proxy): add --openai-api-target and --anthropic-api-target flags by @claude in #1249
- fix: push only tag in release workflow to avoid branch protection violation by @Copilot in #1258
- fix: make release workflow compatible with branch protection by @Mossaka in #1260
Full Changelog: v0.23.1...v0.24.0
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
-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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1773339200015")
-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 images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--memory-limit <limit> Memory limit for the agent container (e.g., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for GitHub Copilot API requests in the api-proxy sidecar.
Defaults to api.githubcopilot.com. Useful for GHES deployments.
Can also be set via COPILOT_API_TARGET env var.
--openai-api-target <host> Target hostname for OpenAI API requests in the api-proxy sidecar.
Defaults to api.openai.com. Useful for custom OpenAI-...
Contributors
claude and Mossaka
Assets 8
Release v0.23.1
What's Changed
Other Changes
- docs: add sandbox design rationale (Docker vs microVMs) by @Mossaka in #1025
- fix: always set NO_PROXY to bypass Squid for localhost by @Mossaka in #1032
- chore: remove smoke-gemini workflow by @Mossaka in #1033
- feat: group --help flags by category, hide dev-only options by @Mossaka in #1035
- docs: add integration test coverage guide with gap analysis by @Mossaka in #1036
- test: add --block-domains integration tests by @Mossaka in #1051
- test: add --env-all integration tests by @Mossaka in #1053
- test: add package installation integration tests by @Mossaka in #1052
- feat: add API proxy port 10004 for OpenCode engine by @Mossaka in #1055
- refactor: remove --allow-full-filesystem-access flag by @Mossaka in #1056
- feat(proxy): add observability and rate limiting to API proxy by @Mossaka in #1038
- feat(proxy): make copilot api target configurable for enterprise envi… by @lpcox in #1063
Full Changelog: v0.23.0...v0.23.1
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1772127942020")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for GitHub Copilot API requests in the api-proxy sidecar.
Defaults to api.githubcopilot.com. Useful for GHES deployments.
Can also be set via COPILOT_API_TARGET env var.
--rate-limit-rpm <n> Enable rate limiting: max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Enable rate limiting: max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> Enable rate limiting: max request bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Explicitly disable rate limiting in the API proxy (requires --enable-api-proxy)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
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.23.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.1/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.23.1/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.1/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.23.1/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.1/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.23.1/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.23.1/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-doma...Contributors
Mossaka and lpcox
Assets 8
Release v0.23.0
What's Changed
Other Changes
- feat: update agentic workflows to v0.47.0 and add smoke-gemini by @Copilot in #974
- docs: add releasing.md link to CLAUDE.md by @Mossaka in #981
- fix: add iptables bypass for container self-traffic by @Copilot in #977
- chore: remove _codeql_detected_source_root by @Copilot in #975
- docs: update runner and architecture compatibility by @Mossaka in #992
- feat(docker): pre-seed Maven/Gradle/sbt proxy config in agent container by @Mossaka in #991
Full Changelog: v0.20.2...v0.23.0
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1771974944141")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
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.23.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.0/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.23.0/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.0/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.23.0/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.0/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.23.0/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.23.0/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.23.0/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.23.0ghcr.io/github/gh-aw-firewall/agent:0.23.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://g...Contributors
Mossaka
Assets 8
Release v0.20.2
What's Changed
Other Changes
- feat: simplify release to workflow_dispatch only by @Mossaka in #968
- fix: add writable tmpfs for /host/dev/shm (POSIX semaphores) by @Mossaka in #972
- Add macOS binary support (Darwin x64 and ARM64) by @Mossaka in #973
- feat: set NO_COLOR=1 in agent container environment by @Mossaka in #971
Full Changelog: v0.20.1...v0.20.2
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1771537717748")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
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.20.2/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.2/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.20.2/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.2/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.20.2/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.2/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.20.2/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.2/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.20.2/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.20.2ghcr.io/github/gh-aw-firewall/agent:0.20.2ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.20.2For detailed instructions including SBOM verification, see [docs/image-verificatio...
Contributors
Mossaka
Assets 8
Release v0.20.1
What's Changed
Other Changes
- feat(api-proxy): centralize port configuration in types.ts by @claude in #955
- docs: add api-proxy image publishing details to release guide by @Copilot in #954
- feat: add ARM64 binary support for awf CLI by @Mossaka in #965
Full Changelog: v0.20.0...v0.20.1
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1771474872794")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (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 architecture (x86_64 or aarch64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.1/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.1/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.1/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.20.1/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.20.1ghcr.io/github/gh-aw-firewall/agent:0.20.1ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.20.1For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude and Mossaka
Assets 6
Release v0.20.0
What's Changed
Other Changes
- chore: reduce dependabot PR volume to ~5/week by @Mossaka in #937
- docs: convert API proxy docs to Starlight format by @Mossaka in #941
- feat: add github copilot api proxy support by @Copilot in #945
Full Changelog: v0.19.1...v0.20.0
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1771373312148")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.20.0/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.20.0/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.20.0ghcr.io/github/gh-aw-firewall/agent:0.20.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.20.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.19.1
What's Changed
Documentation
- [docs] docs: add AWF_ONE_SHOT_TOKEN_DEBUG documentation by @github-actions[bot] in #867
Other Changes
- perf: parallelize container image builds in release workflow by @Mossaka in #909
- fix: remove .claude.json file bind mount regression by @Mossaka in #911
Full Changelog: v0.19.0...v0.19.1
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1771287437558")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.19.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.19.1/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.19.1/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.19.1ghcr.io/github/gh-aw-firewall/agent:0.19.1ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.19.1For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.19.0
What's Changed
Documentation
- [docs] Sync CLI flags and agent image presets with code by @github-actions[bot] in #861
Other Changes
- feat: add AWF_ONE_SHOT_TOKEN_DEBUG env var for silent-by-default logging by @claude in #864
- feat: add ARM64 multi-architecture container builds by @Mossaka in #869
Full Changelog: v0.18.0...v0.19.0
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1771266748347")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.19.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.19.0/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.19.0/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.19.0ghcr.io/github/gh-aw-firewall/agent:0.19.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.19.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude and Mossaka
Assets 5
Release v0.18.0
What's Changed
Documentation
- [docs] docs: sync version requirements with package.json by @github-actions[bot] in #848
Other Changes
- feat: proxy claude api calls to secure auth token by @claude in #849
- feat: disable codex credential sharing, enable proxied calls by @claude in #854
- chore: bump version to 0.17.1 by @claude in #853
- chore: bump version to 0.17.1 by @claude in #855
- chore: bump version to 0.17.2 by @claude in #856
- chore: bump version to 0.18.0 by @claude in #858
Full Changelog: v0.17.0...v0.18.0
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
--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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
--keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1771104976121")
--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 (default: "latest")
--skip-pull Use local images without pulling from registry (requires images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.18.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.18.0/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.18.0/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.18.0ghcr.io/github/gh-aw-firewall/agent:0.18.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.18.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude