Agentic Workflow Firewall

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! ✨

How it works

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

Requirements

• 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.

Get started fast

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.com

The -- separator divides firewall options from the command to run.

Explore the docs

• 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

Development

• Install dependencies: npm install
• Run tests: npm test
• Build: npm run build

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT