README.md

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)

See Compatibility for full details on supported versions and tested configurations.

Get started fast

sudo awf --allow-domains github.com -- curl https://api.github.com

For CI, prefer the setup action pinned to a reviewed commit. For local installation, first obtain and review install.sh through an independently authenticated channel. The installer requires a trusted gh CLI with GitHub authentication; because sudo normally changes HOME and drops tokens, pass the token explicitly:

gh auth status
export GH_TOKEN="$(gh auth token)"
sudo --preserve-env=GH_TOKEN bash ./install.sh
unset GH_TOKEN

Do not pipe an unauthenticated download into sudo bash. See release security for the initial trust requirements.

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 <path> 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
• Unified enclaves: isolated script and agent execution with cost control via --max-num-tool-calls, repository seeding, and dynamic admission
• Infrastructure flexibility: upstream proxy chaining, host service access, Docker-in-Docker, custom mounts, memory limits, and TTY mode
• Protected output capture: opt-in, host-only command stdout/stderr capture with attempt and completeness metadata
• 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
  • awf logs stats — aggregate traffic statistics
  • awf logs summary — markdown/json summaries (great for GitHub Actions step summaries)
  • awf logs audit — audit view with policy-rule matching (requires policy-manifest.json, typically from --audit-dir)

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
• Protected command output capture — isolated raw stdout/stderr capture and completion metadata
• 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
• Emergency CA distrust — compromised CA mitigations, rollout, and runtime trust boundaries
• Architecture — how Squid, Docker, and iptables fit together
• Filesystem Sharing Contract — component identities, host permissions, generated access inventory, and runtime verification
• 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

The model-routing smoke workflow builds the router from containers/router and the API proxy from containers/api-proxy, and runs live routed inference through AWF with both. Its planning smoke also checks the router against a digest-pinned released API-proxy image.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT