# 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](https://github.com/github/gh-aw). For more background, check out the [project page](https://github.github.io/gh-aw/)! ✨
## 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](docs/compatibility.md) for full details on supported versions and tested configurations.
## Get started fast
```bash
sudo awf --allow-domains github.com -- curl https://api.github.com
```
For CI, prefer the [setup action](docs/github_actions.md) 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:
```bash
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](docs/releasing.md#initial-trust-is-a-prerequisite-not-something-the-installer-can-create)
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
```yaml
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](docs/github_actions.md) for advanced setup and `awf logs summary` examples.
## Explore the docs
- [Quick start](docs/quickstart.md) — install, verify, and run your first command
- [Usage guide](docs/usage.md) — CLI flags, domain allowlists, examples
- [AWF config schema](docs/awf-config.schema.json) — machine-readable JSON Schema for JSON/YAML configs (also published as a [versioned release asset](https://github.com/github/gh-aw-firewall/releases/latest/download/awf-config.schema.json) for IDE autocomplete)
- [AWF config spec](docs/awf-config-spec.md) — normative processing and precedence rules for tooling/compiler integration
- [Unified enclave architecture](docs/enclaves-architecture.md) — AWF-owned enclave MCP server, mcpg-only access, and the `enclave_run_script` / `enclave_run_agent` tools for private-repository execution
- [Public enclave diagnostics exporter](docs/cloud-hypervisor-foundation.md#shared-public-diagnostics-exporter) — version-pinned Docker and Cloud Hypervisor collection, safe upload handoff, and failure reporting
- [Audit log schema](schemas/audit.schema.json) — JSON Schema for L7 traffic audit records (`audit.jsonl`)
- [Token usage schema](schemas/token-usage.schema.json) — JSON Schema for per-call token usage records (`token-usage.jsonl`)
- [Schemas README](schemas/README.md) — versioning policy, record identification, and validation examples
- [Enterprise configuration](docs/enterprise-configuration.md) — GitHub Enterprise Cloud and Server setup
- [Chroot mode](docs/chroot-mode.md) — use host binaries with network isolation (glibc-based daemon hosts)
- [API proxy sidecar](docs/api-proxy-sidecar.md) — secure credential management for LLM APIs
- [Authentication architecture](docs/authentication-architecture.md) — deep dive into token handling and credential isolation
- [Authentication matrix](docs/auth-matrix.md) — supported static, BYOK, and OIDC provider combinations
- [Protected command output capture](docs/protected-command-output.md) — isolated raw stdout/stderr capture and completion metadata
- [SSL Bump](docs/ssl-bump.md) — HTTPS content inspection for URL path filtering
- [GitHub Actions](docs/github_actions.md) — CI/CD integration and MCP server setup
- [Environment variables](docs/environment.md) — passing environment variables to containers
- [Logging quick reference](docs/logging_quickref.md) and [Squid log filtering](docs/squid_log_filtering.md) — view and filter traffic
- [Security model](docs/security.md) — what the firewall protects and how
- [Emergency CA distrust](docs/security-ca-trust.md) — compromised CA mitigations, rollout, and runtime trust boundaries
- [Architecture](docs/architecture.md) — how Squid, Docker, and iptables fit together
- [Filesystem Sharing Contract](docs/filesystem-sharing-contract.md) — component identities, host permissions, generated access inventory, and runtime verification
- [Compatibility](docs/compatibility.md) — supported Node.js, OS, and Docker versions
- [Troubleshooting](docs/troubleshooting.md) — common issues and fixes
- [Diagnosing AWF failures](docs/diagnosing-awf-failures.md) — use the Self-Hosted Runner Doctor agent to triage self-hosted/ARC/GHES/GHEC failures
- [Diagnosis registry](docs/diagnostics/README.md) — canonical, machine-readable AWF diagnosis findings and the `diagnose-awf` agent entry point
- [Auth Doctor Updater workflow](.github/workflows/auth-doctor-updater.md) — daily/manual audit that opens bounded PRs with evidence-backed authentication and API-proxy documentation corrections
- [Image verification](docs/image-verification.md) — cosign signature verification
- [Cloud Hypervisor integration (preview)](docs/cloud-hypervisor-foundation.md) — 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)](docs/nvx-security-design.md) — 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](.github/workflows/test-model-routing.yml) 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](CONTRIBUTING.md) for guidelines.
## License
[MIT](LICENSE)