Sandbox Security Architecture in GitHub gh-aw: How Agent Execution Isolation Works

The gh-aw sandbox security architecture implements a layered isolation model that runs AI agents inside an OS-level container (AWF) with chroot filesystem restrictions, network egress controls, and a centralized MCP gateway for auditing all external tool calls.

The sandbox security architecture in github/gh-aw provides defense-in-depth for AI agent execution by combining container isolation with protocol-level traffic control. This architecture ensures that agent workflows run inside a restricted environment where filesystem access, network egress, and tool invocations are strictly governed through the Agent Workflow Firewall (AWF).

Layered Security Components of the Sandbox Architecture

Agent Workflow Firewall (AWF) for OS-Level Isolation

The Agent Workflow Firewall (AWF) provides the foundational isolation layer for the AI engine. Defined in pkg/workflow/sandbox.go, the AgentSandboxConfig type specifies the container configuration including id, command, args, env, and mounts. When no sandbox is explicitly configured, applySandboxDefaults automatically creates a default configuration with type: awf, ensuring every workflow runs inside the firewall unless explicitly disabled.

Chroot Mode for Filesystem Sandboxing

Chroot mode enhances the AWF container by creating a restricted filesystem view. As documented in docs/src/content/docs/reference/sandbox.md, this mode gives the agent full read-write access to user-owned paths while rendering system directories read-only. The AWF binary invoked during workflow compilation sets up this chroot environment, preventing the agent from accessing sensitive host filesystem locations outside the mounted scopes.

Network Firewall and Egress Controls

The architecture restricts outbound traffic through an integrated network firewall layer. Configured via the top-level network field in the workflow definition, this layer uses iptables and Squid proxy rules to limit egress to explicitly allowed domains. The firewall automatically attaches to the AWF container, ensuring that even if the agent attempts network communication, it can only reach approved endpoints.

MCP Gateway for Centralized Tool Call Routing

The MCP gateway ensures that every Model-Context-Protocol (MCP) tool call funnels through a single HTTP proxy. Defined in sandbox.go as MCPGatewayRuntimeConfig and validated in sandbox_validation.go, this gateway enables central logging, authentication, and version control for all external tool invocations. When features.mcp-gateway: true is set, the workflow compiler launches the gateway process and rewrites MCP tool definitions to point at http://localhost:<port>.

How the Sandbox Isolation Flow Works

The sandbox security architecture enforces isolation through a five-stage pipeline implemented in the workflow compiler:

1. Workflow Parsing – The front-matter is read from the workflow file. If legacy SRT (Secure Runtime) settings are detected, migrateSRTToAWF in sandbox.go automatically migrates them to the modern AWF configuration.

2. Default Application – If no sandbox configuration exists, applySandboxDefaults creates an AgentSandboxConfig with type: awf, ensuring isolation is opt-out rather than opt-in.

3. Validation – validateSandboxConfig in sandbox_validation.go checks mount syntax via validateMountsSyntax, ensures MCP is enabled when the agent sandbox is active, and rejects deprecated sandbox.config fields.

4. Runtime Generation – The workflow emitter writes an AWF step that invokes the AWF binary inside the chroot, adds --env-all to pass environment variables, and attaches any custom mounts specified in the configuration.

5. MCP Gateway Startup – If the MCP gateway feature is enabled, a separate process launches on the configured port; all MCP tool definitions are rewritten to route through http://localhost:<port>, ensuring centralized auditing.

Configuring the Sandbox Security Architecture

Minimal Configuration with Default AWF

The simplest configuration relies on the automatic defaults defined in pkg/workflow/sandbox.go:

sandbox:
  agent: awf          # Optional; this is the default

When sandboxConfig == nil, applySandboxDefaults (lines 46‑53 in sandbox.go) automatically creates this configuration with SandboxTypeAWF.

Disabling the Agent Sandbox

To run workflows without OS-level isolation while retaining the MCP gateway:

sandbox:
  agent: false       # Disables AWF firewall; MCP gateway stays active

The Disabled flag in AgentSandboxConfig (line 47 in sandbox.go) handles this state. Validation in validateSandboxConfig (lines 91‑98 in sandbox_validation.go) permits this configuration in non-strict mode.

Custom Mounts and Environment Variables

Expose host directories and set custom environment variables within the chroot:

sandbox:
  agent:
    id: awf
    mounts:
      - "/host/data:/data:ro"
      - "/tmp/cache:/cache:rw"
    env:
      DEBUG_LEVEL: "verbose"

The validateMountsSyntax function (lines 23‑73 in sandbox_validation.go) validates the source:dest:mode format. The Env map in AgentSandboxConfig (line 51 in sandbox.go) passes these variables to the AWF step with --env-all.

Enabling the MCP Gateway

Route all MCP tool calls through the centralized gateway:

features:
  mcp-gateway: true

sandbox:
  mcp:
    port: 8080
    api-key: "${{ secrets.MCP_GATEWAY_API_KEY }}"

The MCPGatewayRuntimeConfig type (referenced in sandbox.go line 36) defines this structure. The validateIntRange function (lines 19‑23 in sandbox_validation.go) ensures the port is within valid ranges.

Full Combined Configuration Example

Combine OS-level isolation with MCP gateway auditing:

features:
  mcp-gateway: true

sandbox:
  agent: awf
  mcp:
    port: 8080

This configuration leverages applySandboxDefaults for the AWF setup while explicitly enabling the MCP gateway for centralized tool call management.

Key Implementation Files

File	Role
pkg/workflow/sandbox.go	Core sandbox types, default handling, migration from legacy SRT, and applySandboxDefaults
pkg/workflow/sandbox_validation.go	Validation of mounts, deprecated fields, MCP port, and agent-MCP coupling
docs/src/content/docs/reference/sandbox.md	User-focused documentation of the architecture, chroot mode, mounts, environment, and MCP gateway
pkg/workflow/sandbox_test.go	Unit tests for defaulting, migration, and validation logic
pkg/workflow/sandbox_custom_agent_test.go	Tests custom command/args/env handling for the agent sandbox

Summary

• The sandbox security architecture in github/gh-aw uses the Agent Workflow Firewall (AWF) to provide OS-level container isolation for AI agents.
• Chroot mode restricts filesystem access by making system directories read-only while allowing user-owned path access.
• Network firewall rules limit outbound traffic to explicitly allowed domains via iptables and proxy configurations.
• The MCP gateway centralizes all Model-Context-Protocol tool calls through a single HTTP proxy for auditing and authentication.
• Configuration is handled through pkg/workflow/sandbox.go with validation in sandbox_validation.go, supporting custom mounts, environment variables, and legacy migration via migrateSRTToAWF.

Frequently Asked Questions

What is the Agent Workflow Firewall (AWF) in gh-aw?

The Agent Workflow Firewall (AWF) is the core isolation container that runs the AI engine in github/gh-aw. Implemented in pkg/workflow/sandbox.go through the AgentSandboxConfig type, the AWF provides OS-level process isolation, network egress restrictions, and optional chroot filesystem sandboxing. When no sandbox is explicitly configured, applySandboxDefaults automatically instantiates an AWF container to ensure secure-by-default execution.

How does chroot mode enhance sandbox security?

Chroot mode strengthens the sandbox security architecture by creating a restricted filesystem view for the AWF container. As documented in docs/src/content/docs/reference/sandbox.md, this mode mounts user-owned paths with read-write permissions while rendering system directories read-only. The implementation occurs in the AWF binary invoked during workflow compilation, preventing the AI agent from accessing sensitive host filesystem locations outside explicitly mounted scopes, even if the container isolation were compromised.

Can I disable the agent sandbox while keeping the MCP gateway active?

Yes, you can disable the OS-level agent sandbox while retaining the MCP gateway for tool call auditing. Set sandbox.agent: false in your configuration to disable the AWF firewall; the Disabled flag in AgentSandboxConfig (pkg/workflow/sandbox.go line 47) handles this state. The validateSandboxConfig function in sandbox_validation.go permits this configuration in non-strict mode, allowing the MCP gateway to continue routing and logging tool calls without container isolation overhead.

Where are sandbox configurations validated in the codebase?

Sandbox configurations undergo rigorous validation in pkg/workflow/sandbox_validation.go. The validateSandboxConfig function orchestrates checks including mount syntax validation via validateMountsSyntax (lines 23-73), port range verification via validateIntRange (lines 19-23), and agent-MCP coupling validation to ensure MCP is enabled when the agent sandbox is active. This validation layer rejects deprecated fields like sandbox.config and enforces the source:dest:mode format for mount specifications before runtime generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}