A network firewall for agentic workflows that restricts outbound HTTP/HTTPS to an allowlist of domains.
Tip
This project is a part of GitHub's explorations of Agentic Workflows. For more background, check out the project page! ✨
awf runs your command inside a Docker sandbox with three containers:
- Squid proxy — filters outbound traffic by domain allowlist
- Agent — runs your command; all HTTP/HTTPS is routed through Squid
- API proxy sidecar (optional) — holds LLM API keys so they never reach the agent process
- Docker: 20.10+ with Docker Compose v2
- Node.js: 20.12.0+ (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
- Enterprise configuration — GitHub Enterprise Cloud and Server setup
- Chroot mode — use host binaries with network isolation
- API proxy sidecar — secure credential management for LLM APIs
- Authentication architecture — deep dive into token handling and credential 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.