Control network access for AI engines using the top-level network field to specify which domains and services your agentic workflows can access during execution. Supported by all four engines (Copilot, Claude, Codex, Gemini) via the AWF firewall.

If no network: permission is specified, it defaults to network: defaults, which allows basic infrastructure domains (certificates, JSON schema, Ubuntu, common package mirrors, Microsoft sources).

Tip

Network permissions follow the principle of least privilege:

• Default (network: defaults) allows basic infrastructure only.
• Selective (network: { allowed: [...] }) allows only the listed domains or ecosystems.
• No access (network: {}) blocks all network access.

Listed domains automatically match all subdomains; wildcard patterns (*.example.com) are also supported — see Wildcard Domain Patterns.

network:
  allowed:
    - defaults              # Basic infrastructure
    - python               # Python/PyPI ecosystem
    - node                 # Node.js/NPM ecosystem
    - "api.example.com"    # Custom domain

Use the blocked field to exclude specific domains or ecosystems from the allowed set. Blocked entries take precedence over allowed ones and include all subdomains — useful for privacy (block trackers), security (block known-bad domains), or compliance:

network:
  allowed:
    - defaults
    - github
    - node
  blocked:
    - python               # Block Python ecosystem
    - "cdn.example.com"    # Block specific CDN

Restrict domains to a specific protocol (HTTP or HTTPS only) for legacy systems, strict HTTPS enforcement, or gradual migration. Currently supported by the Copilot and Claude engines with AWF firewall enabled; domains without a protocol prefix allow both HTTP and HTTPS.

engine: copilot
network:
  allowed:
    - "https://secure.api.example.com"   # HTTPS-only access
    - "http://legacy.example.com"        # HTTP-only access
    - "example.org"                      # Both protocols (default)
    - "https://*.api.example.com"        # HTTPS wildcard

The network: configuration also controls which domains are allowed in sanitized content. URLs from domains not in the allowed list are replaced with (redacted) to prevent potential data exfiltration through untrusted links.

Tip

GitHub domains (github.com, githubusercontent.com, etc.) are always allowed by default.

Mix ecosystem identifiers with specific domains for fine-grained control:

Engine domain sets are named allow-list bundles for engine CLI authentication and direct provider transport. They are not added automatically. Add the matching identifier to network.allowed only when the agent needs direct egress to that engine’s domains; agent inference normally runs through the AWF API proxy.

Single-word entries in network.allowed that match the ecosystem identifier pattern ([a-z][a-z0-9-]*) are validated against the known ecosystem list at compile time. An unrecognized identifier produces a compilation error with the full list of valid options:

# ✗ Compilation error: 'rustxxxx' is not a valid ecosystem identifier
network:
  allowed:
    - defaults
    - rustxxxx

# ✓ Use the correct identifier
network:
  allowed:
    - defaults
    - rust

# ✓ Dotted domain names are validated as domains, not ecosystem identifiers
network:
  allowed:
    - defaults
    - crates.io

When strict mode is enabled (default), strict mode warns when you list individual ecosystem member domains (e.g., pypi.org, npmjs.org) and recommends the ecosystem identifier instead (e.g., python, node). Custom domains outside known ecosystems are allowed without warnings.

# ! Warns: recommend 'python' instead of 'pypi.org'
strict: true
network:
  allowed:
    - defaults
    - "pypi.org"
    - "npmjs.org"

# ✓ No warnings
strict: true
network:
  allowed:
    - defaults
    - python
    - node
    - "api.example.com"  # Custom domain

The emitted message takes the form:

recommend using ecosystem identifiers instead of individual domain names for better maintainability: 'pypi.org' → 'python', 'npmjs.org' → 'node'

All engines (Copilot, Claude, Codex, Gemini) enforce network permissions through AWF (Agent Workflow Firewall) — a wrapper sourced from github.com/github/gh-aw-firewall that enforces domain-based access controls via --allow-domains. AWF automatically includes all subdomains (e.g., github.com allows api.github.com), supports wildcard patterns, and logs all network activity for audit.

engine: copilot          # or claude, codex, gemini
network:
  allowed:
    - defaults             # Basic infrastructure
    - python              # Python ecosystem
    - "api.example.com"   # Custom domain

Each engine has a named domain set for its CLI authentication and model API transport. These sets expand only when explicitly listed in network.allowed and never include the node or python ecosystem registries: selecting an engine does not grant the agent access to registry.npmjs.org, pypi.org, or files.pythonhosted.org. Engine CLIs and SDKs are installed by workflow steps that run on the runner before the sandboxed agent starts, and containerized npx/uvx MCP servers are launched by the MCP gateway outside the agent firewall, so registry access inside the sandbox is not required for them.

This guarantee is scoped to the node and python ecosystems. Some engine domain sets still include unrelated infrastructure domains used by the CLI itself (e.g., ghcr.io, packagecloud.io, packages.microsoft.com for OS-level package/container installation) — those are not language package registries.

To let the agent itself reach engine domains or the node/python registries, opt in explicitly with the matching domain set or ecosystem identifier (copilot, node, python, …) in network.allowed, or declare the corresponding entry under runtimes: for language ecosystems. With network: {} or network: { allowed: [defaults, github] }, those domains stay blocked.

See domains.go for the full lists. This invariant is enforced by TestEngineDefaultDomainsDoNotOverlapEcosystems in domains_package_registry_test.go, which fails the build if any engine’s static default domain list overlaps with the full node or python ecosystem domain sets — including registry entries added after this was written.

Control the verbosity of AWF firewall logs using log-level. Options: debug (verbose), info (default), warn, error.

network:
  firewall:
    log-level: info
  allowed:
    - defaults
    - python

Enable SSL bump to filter HTTPS traffic by URL path patterns instead of just domain names — useful when you need to allow specific API endpoints while blocking others on the same domain. Use allow-urls to specify the permitted HTTPS patterns.

network:
  firewall:
    ssl-bump: true
    allow-urls:
      - "https://github.com/githubnext/*"
      - "https://api.github.com/repos/*/issues"
  allowed:
    - defaults

Security: SSL bump intercepts and decrypts HTTPS as a man-in-the-middle — only enable when URL-level filtering is necessary, and craft allow-urls patterns carefully to avoid breaking legitimate connections. Requires AWF v0.9.0+ and does not apply to Sandbox Runtime (SRT). See Sandbox Configuration for full AWF options.

The firewall is enabled by default via sandbox.agent: awf. When disabled, network permissions still apply for content sanitization but the agent can make unrestricted network requests. Only disable during development or when AWF is incompatible with your workflow; keep it enabled in production.

Reusable workflows compiled to .lock.yml bake their network.allowed into the lock file, so consumers normally can’t extend it without forking. Set network.allowed-input: true to expose a workflow_call input named network_allowed that lets callers add domains or ecosystems at runtime.

The compiled network.allowed remains the baseline; the caller’s value is unioned in before AWF starts, with ecosystem shorthands expanded to their concrete domain sets and the result deduplicated.

# source workflow (compiled to a reusable .lock.yml)
on:
  workflow_call:
network:
  allowed:
    - defaults
  allowed-input: true

# consumer workflow
jobs:
  run:
    uses: owner/repo/.github/workflows/worker.lock.yml@v1
    with:
      network_allowed: rust,github.com

The network_allowed input is a string accepting comma-separated ecosystem identifiers and/or domains. The behavior of the source workflow is unchanged when allowed-input is omitted or false.

Wildcard patterns (*.example.com) match the base domain and all subdomains at any depth, making subdomain intent explicit. Only a single leading wildcard is allowed (*.*.example.com is invalid), and it must be followed by a dot and domain. Both example.com and *.example.com match all subdomains.

network:
  allowed:
    - defaults
    - "*.cdn.example.com"     # Matches img.cdn.example.com, static.cdn.example.com
    - "*.storage.example.com" # Matches files.storage.example.com

If network access is blocked, confirm the required domains or ecosystems are in allowed. Start with network: defaults, then add only what the workflow needs. Violations appear in workflow logs.

Use gh aw logs --run-id <run-id> to identify blocked domains. For deeper analysis, run gh aw audit <run-id>; the Firewall Analysis section shows each domain request with its allow/deny status, request volume, and policy attribution. Pass two run IDs to compare runs:

gh aw audit 12345678              # Single run
gh aw audit 12345678 12345679     # Compare two runs

See the Network Configuration Guide and Audit Commands for more.

See also the Network Configuration Guide, Frontmatter, Tools, Playwright, Audit Commands, and the Security Guide.