Text of github.github.com › gh-aw › reference › sandbox as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Sandbox Configuration | GitHub Agentic Workflows

Skip to main content Sandbox Configuration The sandbox field configures sandbox environments for AI engines (coding agents), providing two main capabilities: Coding Agent Sandbox - Controls the agent runtime security using AWF (Agent Workflow Firewall) Model Context Protocol (MCP) Gateway - Routes MCP server calls through a unified HTTP gateway Configuration Section titled “Configuration” Coding Agent Sandbox Section titled “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 Runtime Profiles Section titled “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.

Privileged profiles invoke the system-installed AWF binary and preserve exported runner variables by name, including on sudo-rs hosts that ignore sudo -E . AWF’s agent credential exclusions still apply; preserving the launcher environment does not grant those credentials to the agent. Prefer nvx for workflows that untrusted actors can trigger, such as those with on.roles: all . The default Docker runtime runs the agent as the runner’s user and shares the runner’s /tmp , so a sandbox escape can reach runner processes and their tokens.

The untrusted-roles-detection linter recommends nvx when such workflows also disable threat detection. 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) Section titled “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 Section titled “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 Section titled “Coding Agent Sandbox Types” AWF (Agent Workflow Firewall) Section titled “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 " Custom CA certificate for the API proxy Section titled “Custom CA certificate for the API proxy” Set sandbox.agent.ca-cert to a host path containing a PEM CA certificate to trust it when verifying upstream TLS connections through AWF’s API proxy.

The file is bind-mounted read-only into the API proxy sidecar. This setting requires AWF v0.28.10 or later. This setting applies to the agent job. The detection job runs separately; see Private CA certificates in Threat detection for its CA inheritance and provisioning behavior. Filesystem Access Section titled “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 Section titled “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> . Host Service Ports ( services: ) Section titled “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 Section titled “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.

Runtime Tools Section titled “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 ) Section titled “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. Release integrity ( sandbox.agent.checksums-sha256 ) Section titled “Release integrity (sandbox.agent.checksums-sha256)” To download an AWF version not covered by the setup action’s built-in pins, set its version and checksum-manifest digest together: sandbox : agent : version : v0.28.62 checksums-sha256 : " 0b03f6ea5b638356a799fa541ade4fd7

The rest of this page is on the live site.