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

> Explore the gh-aw sandbox security architecture and learn how it isolates agent execution with OS-level containers, chroot, network controls, and MCP gateway auditing.

- Repository: [GitHub/gh-aw](https://github.com/github/gh-aw)
- Tags: architecture
- Published: 2026-02-16

---

**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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/sandbox.go) as `MCPGatewayRuntimeConfig` and validated in [`sandbox_validation.go`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/pkg/workflow/sandbox.go):

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

```

When `sandboxConfig == nil`, `applySandboxDefaults` (lines 46‑53 in [`sandbox.go`](https://github.com/github/gh-aw/blob/main/sandbox.go)) automatically creates this configuration with `SandboxTypeAWF`.

### Disabling the Agent Sandbox

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

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

```

The `Disabled` flag in `AgentSandboxConfig` (line 47 in [`sandbox.go`](https://github.com/github/gh-aw/blob/main/sandbox.go)) handles this state. Validation in `validateSandboxConfig` (lines 91‑98 in [`sandbox_validation.go`](https://github.com/github/gh-aw/blob/main/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:

```yaml
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`](https://github.com/github/gh-aw/blob/main/sandbox_validation.go)) validates the `source:dest:mode` format. The `Env` map in `AgentSandboxConfig` (line 51 in [`sandbox.go`](https://github.com/github/gh-aw/blob/main/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:

```yaml
features:
  mcp-gateway: true

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

```

The `MCPGatewayRuntimeConfig` type (referenced in [`sandbox.go`](https://github.com/github/gh-aw/blob/main/sandbox.go) line 36) defines this structure. The `validateIntRange` function (lines 19‑23 in [`sandbox_validation.go`](https://github.com/github/gh-aw/blob/main/sandbox_validation.go)) ensures the port is within valid ranges.

### Full Combined Configuration Example

Combine OS-level isolation with MCP gateway auditing:

```yaml
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`](https://github.com/github/gh-aw/blob/main/pkg/workflow/sandbox.go) | Core sandbox types, default handling, migration from legacy SRT, and `applySandboxDefaults` |
| [`pkg/workflow/sandbox_validation.go`](https://github.com/github/gh-aw/blob/main/pkg/workflow/sandbox_validation.go) | Validation of mounts, deprecated fields, MCP port, and agent-MCP coupling |
| [`docs/src/content/docs/reference/sandbox.md`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/pkg/workflow/sandbox_test.go) | Unit tests for defaulting, migration, and validation logic |
| [`pkg/workflow/sandbox_custom_agent_test.go`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/pkg/workflow/sandbox.go) with validation in [`sandbox_validation.go`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/pkg/workflow/sandbox.go) line 47) handles this state. The `validateSandboxConfig` function in [`sandbox_validation.go`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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.