Sandbox Configuration

The sandbox field configures sandbox environments for AI engines (coding agents), providing two main capabilities:

1. Coding Agent Sandbox - Controls the agent runtime security using AWF (Agent Workflow Firewall)
2. Model Context Protocol (MCP) Gateway - Routes MCP server calls through a unified HTTP gateway

Configuration

Coding Agent Sandbox

Configure the coding agent sandbox type to control how the AI engine is isolated:

# Use AWF (Agent Workflow Firewall) - default
sandbox:
  agent: awf

# Disable coding agent sandbox - requires an explicit feature flag
features:
  dangerously-disable-sandbox-agent: true
sandbox:
  agent: false

# Or omit sandbox entirely to use the default (awf)

Default Behavior

If sandbox is not specified in your workflow, it defaults to sandbox.agent: awf. The coding agent sandbox is recommended for all workflows.

Disabling Coding Agent Sandbox

Setting sandbox.agent: false disables the agent firewall while keeping the MCP gateway enabled. This removes a trust boundary and is only supported when strict: false.

To disable the agent sandbox, you must set features.dangerously-disable-sandbox-agent: true. Missing, false, and non-boolean values are rejected by the compiler.

features:
  dangerously-disable-sandbox-agent: true
sandbox:
  agent: false
strict: false

Caution

Disabling the agent sandbox removes a security trust boundary and is always rejected in strict mode. Only use this opt-out in controlled environments where the agent can be trusted with direct network access.

Runtime Profiles

sandbox.agent.runtime is the single selector for the sandbox security and topology profile. Each value resolves to one supported combination of container runtime, AWF privileges, and host access:

Runtime	Effective behavior
docker (default)	Default Docker runtime, rootless AWF, network isolation
docker-sudo-iptables	Docker with privileged AWF, legacy iptables networking, and host/service access
cloud-hypervisor	Preview KVM runtime with its required privileged launcher
nvx	Fail-closed preview NVX one-shot microVM; requires explicit configuration and a Linux x86_64 KVM host

Omitting runtime is equivalent to runtime: docker, which keeps the secure default.

The nvx runtime never falls back to another runtime. It requires a workload-specific guest layer, the AWF release’s provenance bundle and manifest, and all three security opt-ins. The compiler checks the host and verifies the offline attestation before starting AWF. See Agent Runtime Selection for the complete configuration and compatibility requirements.

sandbox:
  agent:
    runtime: docker-sudo-iptables
    allow-host-ports: [9000]

The compiler derives every privilege the selected runtime needs. Unsupported combinations, such as allow-host-ports outside docker-sudo-iptables, fail at compile time. See Agent Runtimes for runner prerequisites.

MCP Gateway (Experimental)

Route MCP server calls through a unified HTTP gateway:

features:
  mcp-gateway: true

sandbox:
  mcp:
    port: 8080
    agent-id: "${{ secrets.MCP_GATEWAY_AGENT_ID }}"

Combined Configuration

Use both coding agent sandbox and MCP gateway together:

features:
  mcp-gateway: true

sandbox:
  agent: awf
  mcp:
    port: 8080

Coding Agent Sandbox Types

AWF (Agent Workflow Firewall)

AWF is the default coding agent sandbox that provides network egress control through domain-based access controls. Network permissions are configured through the top-level network field.

sandbox:
  agent: awf

network:
  firewall: true
  allowed:
    - defaults
    - python
    - "api.example.com"

Filesystem Access

AWF makes the host filesystem visible inside the container with appropriate permissions:

Path Type	Mode	Examples
User paths	Read-write	$HOME, $GITHUB_WORKSPACE, /tmp
System paths	Read-only	/usr, /opt, /bin, /lib
Docker socket	Hidden	/var/run/docker.sock (security)

Host Binaries

All host binaries are available without explicit mounts: system utilities, gh, language runtimes, build tools, and anything installed via apt-get or setup actions. Verify with which <tool>.

Caution

Docker socket is hidden for security. Agents cannot spawn containers.

Host Service Ports (services:)

The AWF sandbox reaches GitHub Actions services: containers through --allow-host-service-ports, which resolves each service’s actual (possibly dynamically assigned) host port at runtime. This mechanism, and the explicit allow-host-ports escape hatch below, both require sandbox.agent.runtime: docker-sudo-iptables: the default (strict) runtime profile does not provide a route to host services, even when host-access flags are combined.

sandbox:
  agent:
    runtime: docker-sudo-iptables

services:
  postgres:
    image: postgres:18
    ports:
      - 5432:5432

For host daemons that are not declared in services:, add an explicit allowlist (also docker-sudo-iptables only):

sandbox:
  agent:
    runtime: docker-sudo-iptables
    allow-host-ports: [9000]

Use allow-host-ports only for ports that cannot be represented by services:. The compiler rejects values outside the TCP port range 1 through 65535, and rejects ports AWF always blocks as dangerous (e.g. 22, 3306, 5432, 6379, 9200) — reach those through services: instead.

Environment Variables

AWF passes all environment variables via --env-all. The host PATH is captured as AWF_HOST_PATH and restored inside the container, preserving setup action tool paths.

Note

Go’s “trimmed” binaries require GOROOT - AWF automatically captures it after actions/setup-go.

Runtime Tools

Setup actions work transparently. Runtimes update PATH, which AWF captures and restores inside the container.

---
jobs:
  setup:
    steps:
      - uses: actions/setup-go@v5
        with:
          go-version: '1.25'
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
---

Use `go build` or `python3` - both are available.

Memory Limit (sandbox.agent.memory)

By default, AWF uses its own built-in memory limit for the agent container. Set sandbox.agent.memory to override this limit on large-memory runners:

sandbox:
  agent:
    memory: 8g

Valid values are a positive integer followed by a unit: b, k, m, or g (case-insensitive). Examples: 512m, 4g, 8g, 1024m.

When omitted, AWF’s own default memory limit applies. Specifying an invalid format (e.g., 48gb or 48) is rejected at compile time.

Note

Exit code 137 means the process received SIGKILL. A memory limit can be one cause, but verify with logs before changing memory. If you increase memory, leave headroom for the runner OS and other processes.

Model fallback (sandbox.agent.model-fallback)

AWF’s API proxy resolves unrecognized model selections against its built-in model catalog and may rewrite them. Set model-fallback: false to pass the configured model through to the provider verbatim:

sandbox:
  agent:
    model-fallback: false

This is required for providers whose model identifiers are not in the built-in catalog (BYOK Azure OpenAI deployment names, self-hosted routers), where rewriting causes HTTP 404 model_not_found. When an OPENAI_BASE_URL or ANTHROPIC_BASE_URL custom endpoint is configured in engine.env, model fallback is disabled automatically; set this field explicitly to override that default.

Token steering (sandbox.agent.token-steering)

AWF enables API proxy token steering by default. To keep the explicitly configured provider and model, disable it for a workflow:

sandbox:
  agent:
    token-steering: false

With steering enabled, AWF adds a notice to the next eligible model request after the run crosses 80, 90, 95 or 99% of its AI-credit budget, its effective-token budget or its runtime deadline. Runtime notices need an agent deadline, which gh-aw sends with AWF v0.28.51 or newer on runtimes other than Cloud Hypervisor and NVX:

• Literal timeout-minutes (for example timeout-minutes: 30): the AWF config gets container.agentTimeout set to that value.
• Expression timeout, including the default that workflows without timeout-minutes compile to (${{ fromJSON(vars.GH_AW_DEFAULT_TIMEOUT_MINUTES || '20') }}): the agent step gets the step timeout in GH_AW_ENGINE_STEP_TIMEOUT_MINUTES, and awf receives it at run time as --agent-timeout. The AWF config has no agentTimeout.