Release v0.5.0

What's Changed

Other Changes

• refactor: rename copilot to agent throughout codebase by @Copilot in #59
• docs: add landing page and security documentation by @Copilot in #56
• docs: add comprehensive cli reference documentation by @Copilot in #57
• docs: add security architecture diagrams for boundary and github actions by @Copilot in #58

Full Changelog: v0.4.0...v0.5.0

CLI Options

Usage: awf [options] [args...]

Network firewall for agentic workflows with domain whitelisting

Arguments:
  args                                           Command and arguments to execute (use -- to separate from options)

Options:
  -V, --version                                  output the version number
  --allow-domains <domains>                      Comma-separated list of allowed domains (e.g., github.com,api.github.com)
  --allow-domains-file <path>                    Path to file containing allowed domains (one per line or comma-separated, supports # comments)
  --log-level <level>                            Log level: debug, info, warn, error (default: "info")
  --keep-containers                              Keep containers running after command exits (default: false)
  --tty                                          Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
  --work-dir <dir>                               Working directory for temporary files (default: "/tmp/awf-1764188332026")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times) (default: [])
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST) (default: false)
  -v, --mount <host_path:container_path[:mode]>  Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
  --container-workdir <dir>                      Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
  -h, --help                                     display help for command

Installation

Binary Installation (Recommended)

Linux (x64):

curl -L https://github.com/githubnext/gh-aw-firewall/releases/download/v0.5.0/awf-linux-x64 -o awf
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation (Alternative)

# Install from tarball
npm install -g https://github.com/githubnext/gh-aw-firewall/releases/download/v0.5.0/awf.tgz

Requirements

• Docker and Docker Compose must be installed
• For iptables manipulation, run with sudo: sudo awf ...
• Container images will be pulled automatically from GHCR on first run

Verification

Verify checksums after download:

sha256sum -c checksums.txt

Quick Start

# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com

# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user

# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt

# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/githubnext/gh-aw-firewall/squid:0.5.0
• ghcr.io/githubnext/gh-aw-firewall/agent:0.5.0
• ghcr.io/githubnext/gh-aw-firewall/squid:latest
• ghcr.io/githubnext/gh-aw-firewall/agent:latest