# github/gh-aw-firewall architecture

> Architecture diagram of the GitHub repository github/gh-aw-firewall, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/gh-aw-firewall
- Repository: https://github.com/github/gh-aw-firewall

## Overview

1. **What this repo is**
   Agentic Workflow Firewall (AWF) is a Docker-based command runner that wraps an arbitrary user command in a network-restricted sandbox. The core architecture is a host-side CLI that assembles containers, network rules, and optional credential sidecars around the command being executed.

2. **Top-level control plane**
   The main implementation lives in `src/`. It provides the `awf` CLI, option parsing, config loading/validation, command orchestration, and lifecycle management. This layer decides how to translate user intent (`--allow-domains`, `--config`, `--ssl-bump`, etc.) into a runnable sandbox definition.

3. **Sandbox runtime**
   The sandbox is built from multiple Docker containers rather than a single process. The README’s main three-piece flow is real in the repo:
   - **Agent container**: runs the user command.
   - **Squid container**: enforces outbound domain allowlists.
   - **API proxy sidecar**: optional, used to keep LLM credentials out of the agent process.
   Supporting images exist for CLI proxying, build tools, Squid, and Docker-in-Docker variants.

4. **Network enforcement boundary**
   The network boundary is enforced primarily by Squid plus host/container network setup. The host-side modules under `src/host-iptables*` and `src/services/doh-proxy-service.ts` show that AWF controls egress with iptables, DNS handling, and proxy routing, not just application-level filtering. This is the key security boundary for the whole system.

5. **Proxy and traffic mediation**
   The `containers/api-proxy` service is a substantial subsystem of its own. It adapts multiple LLM provider APIs, handles authentication/token providers, rate limiting, request/response transforms, model mapping, token tracking, and observability. It sits between the agent and upstream providers so secrets and billing-related behavior can be isolated from the command being run.

6. **Command execution and container lifecycle**
   `src/container-*`, `src/docker-manager.ts`, `src/services/agent-service.ts`, and related modules coordinate image selection, container start/stop, health checks, retries, and cleanup. This is the orchestration layer that turns config into a running sandbox, then tears it down safely after the command exits.

7. **Configuration and policy model**
   Configuration is first-class. The repo contains JSON Schema files, config mappers, precedence logic, and validation code for CLI flags, YAML/JSON config files, and generated runtime config. Domain rules, URL rules, model policies, and runtime limits are compiled into the execution environment rather than interpreted ad hoc at runtime.

8. **Logging, audit, and post-run analysis**
   Traffic and runtime telemetry are treated as artifacts. `src/logs/`, `src/squid-log-reader.ts`, and the CLI `awf logs` subcommands produce raw, summary, stats, and audit views. Separate schemas define audit and token-usage records, which implies a structured post-processing pipeline rather than just console logs.

9. **Security hardening layers**
   The repo includes seccomp profiles, artifact permission handling, secret redaction, credential-hiding mounts, and shell/bootstrap scripts in `containers/agent`. These are not cosmetic; they form a defense-in-depth layer around the sandbox so secrets, host files, and process capabilities are tightly constrained.

10. **Special execution modes**
   AWF supports variants such as chroot mode, DIND-related setups, host binary access, and workspace/volume mounting strategies. The `src/services/*` and `docs/chroot-mode.md` / `docs/sandbox-design.md` content show that the architecture is parameterized for different host capabilities and deployment environments, not just one fixed container layout.

11. **Developer and release tooling**
   The repository is heavily automated through GitHub Actions workflows, lockfiles, and generated docs/assets. This includes build/test pipelines, security checks, smoke tests, release automation, and workflow-specific maintenance tools. For an architecture diagram, this is the “delivery/ops” boundary around the product, not part of the runtime path.

12. **Documentation and schemas as part of the system**
   Docs are not incidental here: `docs/`, `docs-site/`, and `schemas/` define the contract for config, logs, security model, and integration behavior. The architecture is therefore supported by machine-readable schemas plus human documentation, which likely keeps CLI behavior, container setup, and CI expectations aligned.

Main entry points: [`src/docker-manager.ts`](https://github.com/github/gh-aw-firewall/blob/main/src/docker-manager.ts) (Docker manager), [`src/cli-workflow.ts`](https://github.com/github/gh-aw-firewall/blob/main/src/cli-workflow.ts) (Workflow), [`src/commands/build-config.ts`](https://github.com/github/gh-aw-firewall/blob/main/src/commands/build-config.ts) (Sandbox plan), [`src/services/agent-service.ts`](https://github.com/github/gh-aw-firewall/blob/main/src/services/agent-service.ts) (Agent service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_control["Control plane"]
  node_n_cli["AWF CLI<br/>command entry<br/>[cli.ts]"]
  node_n_cli_workflow["Workflow<br/>run orchestration<br/>[cli-workflow.ts]"]
  node_n_options["Options<br/>flag parsing<br/>[cli-options.ts]"]
  node_n_config["Config model<br/>config loading<br/>[config-file.ts]"]
  node_n_validate["Policy checks<br/>validation layer"]
  node_n_builder["Sandbox plan<br/>config assembly<br/>[build-config.ts]"]
end

subgraph group_group_runtime["Sandbox runtime"]
  node_n_docker[("Docker manager<br/>container orchestration<br/>[docker-manager.ts]")]
  node_n_lifecycle["Lifecycle<br/>container state"]
  node_n_agent_service["Agent service<br/>agent container<br/>[agent-service.ts]"]
  node_n_agent_env["Agent env<br/>env assembly"]
  node_n_agent_volumes["Agent mounts<br/>volume and mount assembly<br/>[agent-volumes.ts]"]
  node_n_api_proxy[("API proxy<br/>llm sidecar")]
  node_n_api_proxy_container["Proxy runtime<br/>provider mediation<br/>[server.js]"]
end

subgraph group_group_policy["Policy and network"]
  node_n_squid_service[("Squid service<br/>egress proxy<br/>[squid-service.ts]")]
  node_n_host_iptables["Host firewall<br/>network boundary<br/>[host-iptables.ts]"]
  node_n_doh["DNS proxy<br/>dns mediation"]
end

subgraph group_group_observability["Observability"]
  node_n_logs["Logs pipeline<br/>audit and stats<br/>[index.ts]"]
end

subgraph group_group_docs["Docs and schemas"]
  node_n_schemas["Schemas<br/>machine-readable contracts<br/>[README.md]"]
  node_n_docs["Docs site<br/>documentation<br/>[architecture.md]"]
  node_n_ci["CI workflows<br/>delivery automation<br/>[build.yml]"]
end

node_n_cli -->|"invokes"| node_n_cli_workflow
node_n_cli_workflow -->|"parses"| node_n_options
node_n_cli_workflow -->|"loads"| node_n_config
node_n_cli_workflow -->|"checks"| node_n_validate
node_n_validate -->|"approves"| node_n_builder
node_n_builder -->|"assembles"| node_n_docker
node_n_docker -->|"controls"| node_n_lifecycle
node_n_docker -->|"starts"| node_n_agent_service
node_n_agent_service -->|"injects"| node_n_agent_env
node_n_agent_service -->|"mounts"| node_n_agent_volumes
node_n_docker -->|"starts"| node_n_squid_service
node_n_docker -->|"optionally starts"| node_n_api_proxy
node_n_api_proxy -->|"runs as"| node_n_api_proxy_container
node_n_builder -->|"configures"| node_n_host_iptables
node_n_builder -->|"configures"| node_n_doh
node_n_host_iptables -->|"funnels traffic"| node_n_squid_service
node_n_squid_service -->|"emits"| node_n_logs
node_n_api_proxy_container -->|"emits"| node_n_logs
node_n_logs -->|"formats"| node_n_schemas
node_n_docs -->|"describes"| node_n_schemas
node_n_ci -->|"checks"| node_n_docs

click node_n_cli "https://github.com/github/gh-aw-firewall/blob/main/src/cli.ts"
click node_n_cli_workflow "https://github.com/github/gh-aw-firewall/blob/main/src/cli-workflow.ts"
click node_n_options "https://github.com/github/gh-aw-firewall/blob/main/src/cli-options.ts"
click node_n_config "https://github.com/github/gh-aw-firewall/blob/main/src/config-file.ts"
click node_n_validate "https://github.com/github/gh-aw-firewall/blob/main/src/commands/validate-options.ts"
click node_n_builder "https://github.com/github/gh-aw-firewall/blob/main/src/commands/build-config.ts"
click node_n_docker "https://github.com/github/gh-aw-firewall/blob/main/src/docker-manager.ts"
click node_n_lifecycle "https://github.com/github/gh-aw-firewall/blob/main/src/container-lifecycle.ts"
click node_n_agent_service "https://github.com/github/gh-aw-firewall/blob/main/src/services/agent-service.ts"
click node_n_agent_env "https://github.com/github/gh-aw-firewall/blob/main/src/services/agent-environment/environment-builder.ts"
click node_n_agent_volumes "https://github.com/github/gh-aw-firewall/blob/main/src/services/agent-volumes.ts"
click node_n_squid_service "https://github.com/github/gh-aw-firewall/blob/main/src/services/squid-service.ts"
click node_n_host_iptables "https://github.com/github/gh-aw-firewall/blob/main/src/host-iptables.ts"
click node_n_doh "https://github.com/github/gh-aw-firewall/blob/main/src/services/doh-proxy-service.ts"
click node_n_api_proxy "https://github.com/github/gh-aw-firewall/blob/main/src/services/api-proxy-service.ts"
click node_n_api_proxy_container "https://github.com/github/gh-aw-firewall/blob/main/containers/api-proxy/server.js"
click node_n_logs "https://github.com/github/gh-aw-firewall/blob/main/src/logs/index.ts"
click node_n_schemas "https://github.com/github/gh-aw-firewall/blob/main/schemas/README.md"
click node_n_docs "https://github.com/github/gh-aw-firewall/blob/main/docs/architecture.md"
click node_n_ci "https://github.com/github/gh-aw-firewall/blob/main/.github/workflows/build.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_cli,node_n_cli_workflow,node_n_options,node_n_config,node_n_validate,node_n_builder toneBlue
class node_n_docker,node_n_lifecycle,node_n_agent_service,node_n_agent_env,node_n_agent_volumes,node_n_api_proxy,node_n_api_proxy_container toneAmber
class node_n_squid_service,node_n_host_iptables,node_n_doh toneMint
class node_n_logs toneRose
class node_n_schemas,node_n_docs,node_n_ci toneIndigo
```

## Components

### Control plane

CLI, config, and orchestration that turn user intent into a runnable sandbox.

- [AWF CLI](https://github.com/github/gh-aw-firewall/blob/main/src/cli.ts): command entry · Top-level command interface and subcommands. · `src/cli.ts`
- [Workflow](https://github.com/github/gh-aw-firewall/blob/main/src/cli-workflow.ts): run orchestration · Coordinates option validation, preflight, and command execution. · `src/cli-workflow.ts`
- [Options](https://github.com/github/gh-aw-firewall/blob/main/src/cli-options.ts): flag parsing · Parses CLI flags and runtime options. · `src/cli-options.ts`
- [Config model](https://github.com/github/gh-aw-firewall/blob/main/src/config-file.ts): config loading · Loads, maps, merges, and validates repo configuration. · `src/config-file.ts`
- [Policy checks](https://github.com/github/gh-aw-firewall/blob/main/src/commands/validate-options.ts): validation layer · Validates domain rules, runtime limits, and assembled config. · `src/commands/validate-options.ts`
- [Sandbox plan](https://github.com/github/gh-aw-firewall/blob/main/src/commands/build-config.ts): config assembly · Builds the runtime execution plan from flags and config. · `src/commands/build-config.ts`

### Sandbox runtime

Containerized execution path and the services that surround the agent.

- [Docker manager](https://github.com/github/gh-aw-firewall/blob/main/src/docker-manager.ts): container orchestration · Starts, stops, inspects, and cleans up containers. · `src/docker-manager.ts`
- [Lifecycle](https://github.com/github/gh-aw-firewall/blob/main/src/container-lifecycle.ts): container state · Tracks startup, retries, health, stop, and cleanup behavior. · `src/container-lifecycle.ts`
- [Agent service](https://github.com/github/gh-aw-firewall/blob/main/src/services/agent-service.ts): agent container · Assembles the command-running container and its runtime environment. · `src/services/agent-service.ts`
- [Agent env](https://github.com/github/gh-aw-firewall/blob/main/src/services/agent-environment/environment-builder.ts): env assembly · Builds environment variables and credential exposure for the agent. · `src/services/agent-environment/environment-builder.ts`
- [Agent mounts](https://github.com/github/gh-aw-firewall/blob/main/src/services/agent-volumes.ts): volume and mount assembly · Constructs workspace, host, system, and secret-hiding mounts. · `src/services/agent-volumes.ts`
- [API proxy](https://github.com/github/gh-aw-firewall/blob/main/src/services/api-proxy-service.ts): llm sidecar · Isolates provider credentials, routing, transforms, rate limits, and token tracking. · `src/services/api-proxy-service.ts`
- [Proxy runtime](https://github.com/github/gh-aw-firewall/blob/main/containers/api-proxy/server.js): provider mediation · Container-side request handling, adapters, guards, and upstream forwarding. · `containers/api-proxy/server.js`

### Policy and network

Egress control, DNS, domain policy, and security boundaries.

- [Squid service](https://github.com/github/gh-aw-firewall/blob/main/src/services/squid-service.ts): egress proxy · Configures the outbound filtering proxy container. · `src/services/squid-service.ts`
- [Host firewall](https://github.com/github/gh-aw-firewall/blob/main/src/host-iptables.ts): network boundary · Sets up host-side iptables rules for egress and host-access control. · `src/host-iptables.ts`
- [DNS proxy](https://github.com/github/gh-aw-firewall/blob/main/src/services/doh-proxy-service.ts): dns mediation · Routes DNS through a controlled proxy path. · `src/services/doh-proxy-service.ts`

### Observability

Log, audit, and telemetry processing paths.

- [Logs pipeline](https://github.com/github/gh-aw-firewall/blob/main/src/logs/index.ts): audit and stats · Discovers, parses, aggregates, and formats runtime and audit logs. · `src/logs/index.ts`

### Docs and schemas

Contracts, docs, and release/developer automation around the product.

- [Schemas](https://github.com/github/gh-aw-firewall/blob/main/schemas/README.md): machine-readable contracts · Defines audit, token usage, proxy access, and telemetry record formats. · `schemas/README.md`
- [Docs site](https://github.com/github/gh-aw-firewall/blob/main/docs/architecture.md): documentation · Human-readable architecture, usage, and security documentation. · `docs/architecture.md`
- [CI workflows](https://github.com/github/gh-aw-firewall/blob/main/.github/workflows/build.yml): delivery automation · Build, test, release, and security automation for the repo. · `.github/workflows/build.yml`

## Connections

- AWF CLI → Workflow: invokes · CLI entry hands off to the main workflow.
- Workflow → Options: parses · Reads flags and user-supplied runtime options.
- Workflow → Config model: loads · Pulls configuration from files and precedence layers.
- Workflow → Policy checks: checks · Validates assembled options and policy constraints.
- Policy checks → Sandbox plan: approves · Validated inputs are turned into an execution plan.
- Sandbox plan → Docker manager: assembles · Produces container definitions and orchestration inputs.
- Docker manager → Lifecycle: controls · Lifecycle manager handles startup, retry, stop, and cleanup.
- Docker manager → Agent service: starts · Creates the agent container as the primary workload.
- Agent service → Agent env: injects · Builds the agent environment with credential and proxy settings.
- Agent service → Agent mounts: mounts · Attaches workspace, system, and secret-hiding volumes.
- Docker manager → Squid service: starts · Creates the egress-filtering Squid sidecar.
- Docker manager → API proxy: optionally starts · Adds the credential-isolating API proxy when needed.
- API proxy → Proxy runtime: runs as · Service is implemented by the proxy container runtime.
- Sandbox plan → Host firewall: configures · Execution plan includes host-side firewall setup.
- Sandbox plan → DNS proxy: configures · Execution plan can route DNS through the proxy service.
- Host firewall → Squid service: funnels traffic · Firewall rules steer egress toward the proxy boundary.
- Squid service → Logs pipeline: emits · Proxy access logs feed the post-run analysis pipeline.
- Proxy runtime → Logs pipeline: emits · Proxy telemetry and access events are analyzed after execution.
- Logs pipeline → Schemas: formats · Structured log outputs follow repo schemas.
- Docs site → Schemas: describes · Docs explain the same contracts encoded in schemas.
- CI workflows → Docs site: checks · Automation validates docs, tests, and release artifacts.
