Agentic Workflow Firewall

[!WARNING]

Releases v0.25.21 through v0.25.39 were retired due to a bug that impacted billing. If you are running one of these versions, please upgrade to the latest release as soon as possible.

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 (always enabled) — holds LLM API keys so they never reach the agent process

Requirements

• Docker: 20.10+ with Docker Compose v2
• Node.js: 20.19.0+ (for building from source)
• OS: Ubuntu 22.04+ or compatible Linux distribution (x86_64 and arm64)

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.

To inspect the API proxy endpoints and models without running an agent command, use awf --reflect. It prints the /reflect JSON response to stdout.

Feature highlights

• Declarative config support: --config with JSON/YAML + published JSON Schema
• Domain and URL controls: allow/deny domain rules, SSL Bump (--ssl-bump), and URL patterns (--allow-urls, requires --ssl-bump)
• Data protection controls: DLP scanning (--enable-dlp), DNS-over-HTTPS, and agent runtime limits (--agent-timeout)
• API proxy capabilities: OpenAI, Anthropic, Copilot, Gemini, and Google Vertex AI targets with rate limits, token steering, Anthropic auto-cache, and apiProxy.hostedWeb.{claude,codex} domain policies
• Infrastructure flexibility: upstream proxy chaining, host service access, Docker-in-Docker, custom mounts, memory limits, and TTY mode
• Operational tooling: pre-download images and inspect logs/stats/summaries/audits from live or saved runs

CLI subcommands

• awf predownload — pre-pull runtime images for faster startup or offline environments
• awf logs — inspect firewall logs in raw/pretty/json

For the complete CLI surface area, run awf --help.

GitHub Action quick start

steps:
  - uses: actions/checkout@v4
  - name: Setup AWF
    uses: github/gh-aw-firewall@v1
  - name: Run command through firewall
    run: sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com

See GitHub Actions for advanced setup and awf logs summary examples.

Explore the docs

• Quick start — install, verify, and run your first command
• Usage guide — CLI flags, domain allowlists, examples
• AWF config schema — machine-readable JSON Schema for JSON/YAML configs (also published as a versioned release asset for IDE autocomplete)
• AWF config spec — normative processing and precedence rules for tooling/compiler integration
• Unified enclave architecture — AWF-owned enclave MCP server, mcpg-only access, and the enclave_run_script / enclave_run_agent tools for private-repository execution
• Audit log schema — JSON Schema for L7 traffic audit records (audit.jsonl)
• Token usage schema — JSON Schema for per-call token usage records (token-usage.jsonl)
• Schemas README — versioning policy, record identification, and validation examples
• Enterprise configuration — GitHub Enterprise Cloud and Server setup
• Chroot mode — use host binaries with network isolation (glibc-based daemon hosts)
• API proxy sidecar — secure credential management for LLM APIs
• Authentication architecture — deep dive into token handling and credential isolation
• Authentication matrix — supported static, BYOK, and OIDC provider combinations
• 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
• Diagnosing AWF failures — use the Self-Hosted Runner Doctor agent to triage self-hosted/ARC/GHES/GHEC failures
• Diagnosis registry — canonical, machine-readable AWF diagnosis findings and the diagnose-awf agent entry point
• Auth Doctor Updater workflow — daily/manual audit that opens bounded PRs with evidence-backed authentication and API-proxy documentation corrections
• Image verification — cosign signature verification
• Cloud Hypervisor integration (preview) — Cloud Hypervisor v53.0 microVM backend: explicit opt-in, GitHub-hosted Ubuntu x86_64 KVM runners only, release-pinned GitHub-attested artifact manifests, Landlock/seccomp-confined launcher in place of a jailer, fail-closed egress, mandatory API proxy credential isolation
• NVX integration (preview) — NVX/OpenVMM one-shot microVM backend: explicit --container-runtime nvx --nvx-preview opt-in, Linux x86_64 KVM-only, disabled by default, never falls back to another runtime, release-pinned GitHub-attested artifact manifests, deny-by-default guest networking, credential-isolated Copilot inference via the API proxy

Development

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

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT