A network firewall for agentic workflows with domain whitelisting. This tool provides L7 (HTTP/HTTPS) egress control using Squid proxy and Docker containers, restricting network access to a whitelist of approved domains for AI agents and their MCP servers.
Tip
This project is a part of GitHub's explorations of Agentic Workflows. For more background, check out the project page! ✨
- L7 Domain Whitelisting: Control HTTP/HTTPS traffic at the application layer
- Host-Level Enforcement: Uses iptables DOCKER-USER chain to enforce firewall on ALL containers
- Chroot Mode: Optional
--enable-chrootfor transparent access to host binaries (Python, Node.js, Go) while maintaining network isolation
- Docker: 20.10+ with Docker Compose v2
- Node.js: 18+ (for building from source)
- OS: Ubuntu 22.04+ or compatible Linux distribution
See Compatibility for full details on supported versions and tested configurations.
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bash
sudo awf --allow-domains github.com -- curl https://api.github.comThe -- separator divides firewall options from the command to run.
- Quick start — install, verify, and run your first command
- Usage guide — CLI flags, domain allowlists, examples
- Chroot mode — use host binaries with network isolation
- SSL Bump — HTTPS content inspection for URL path filtering
- GitHub Actions — CI/CD integration and MCP server setup
- Environment variables — passing environment variables to containers
- Logging quick reference and Squid log filtering — view and filter traffic
- Security model — what the firewall protects and how
- Architecture — how Squid, Docker, and iptables fit together
- Compatibility — supported Node.js, OS, and Docker versions
- Troubleshooting — common issues and fixes
- Image verification — cosign signature verification
- Install dependencies:
npm install - Run tests:
npm test - Build:
npm run build
Contributions welcome! Please see CONTRIBUTING.md for guidelines.