Text of github.github.com › gh-aw › reference › agent-runtimes 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

Agent Runtime Selection | GitHub Agentic Workflows

Skip to main content Agent Runtime Selection Agentic workflows use AWF (Agent Workflow Firewall) to isolate the agent. The supported agent runtime profiles are Docker, privileged Docker with legacy iptables networking, preview Cloud Hypervisor, and preview NVX. ARC DinD is a runner topology, not a value of sandbox.agent.runtime . Runtime and topology fields Section titled “Runtime and topology fields” Field Purpose Supported values sandbox.agent.runtime Selects the isolation backend for the main agent docker , docker-sudo-iptables , cloud-hypervisor , nvx , or omitted for Docker runner.topology Describes how the runner reaches Docker arc-dind , or omitted for a local Docker daemon runtimes Installs language toolchains such as Node.js, Python, and Go Unrelated to agent isolation Choose a runtime Section titled “Choose a runtime” Choice Isolation boundary Runner requirements Main tradeoff Docker Linux namespaces, cgroups, and the host kernel Linux and a usable Docker daemon Broad compatibility; the agent shares the host kernel Docker with legacy iptables Docker with privileged AWF networking and host/service access Linux, Docker, and host privileges Supports host ports and Actions services but increases AWF privileges Cloud Hypervisor (preview) A KVM-backed microVM for the agent GitHub-hosted Ubuntu x86_64 runner with /dev/kvm Stronger isolation with strict host requirements NVX (preview) A one-shot NVX microVM with a workload-specific guest layer Linux x86_64, effective root for AWF, read/write /dev/kvm , cgroup v2 ( cpu , memory , pids ), and seccomp kill_process Strong isolation; requires trusted, attested AWF assets and explicit pre-agent provisioning ARC DinD Standard Docker agent container in a DinD sidecar ARC or equivalent Kubernetes runner with a privileged DinD sidecar and shared work volume Supports Kubernetes runner fleets but adds split-filesystem complexity Use docker-sudo-iptables only when the workflow requires sandbox.agent.allow-host-ports or access to published GitHub Actions services: ports.

Use cloud-hypervisor or nvx only when the runner satisfies the selected preview runtime’s requirements. Otherwise, omit sandbox.agent.runtime to use Docker. Requirements shared by all choices Section titled “Requirements shared by all choices” The main agent job requires a Linux runner with enough CPU, memory, and disk for the agent, AWF, the MCP Gateway, proxy containers, and configured MCP servers. Docker must be reachable by the runner user.

Verify the baseline before investigating a specialized topology: Terminal window docker version docker info docker compose version docker run --rm hello-world The runner also needs outbound HTTPS access to GitHub, the selected AI provider, ghcr.io , and the domains required by setup steps and network.allowed . Docker Section titled “Docker” Docker is the default. Leave sandbox.agent.runtime unset: --- on : issues sandbox : agent : id : awf --- Investigate this issue.

The entire sandbox block may be omitted when its defaults are sufficient. AWF still provides network isolation and proxy enforcement. Docker with host and service access Section titled “Docker with host and service access” Use docker-sudo-iptables when the agent must reach explicitly allowed host ports or published GitHub Actions service ports: --- sandbox : agent : id : awf runtime : docker-sudo-iptables allow-host-ports : [ 8080 ] --- This profile runs AWF with the host privileges required for legacy iptables networking.

Other profiles reject allow-host-ports and published service connectivity. Cloud Hypervisor (preview) Section titled “Cloud Hypervisor (preview)” Cloud Hypervisor runs the agent in a KVM-backed microVM. The microVM runtimes are experimental. It is supported only on GitHub-hosted Ubuntu x86_64 runners with /dev/kvm . --- on : issues sandbox : agent : id : awf runtime : cloud-hypervisor --- Investigate this issue. The compiler verifies the host environment, downloads and checksum-verifies the Cloud Hypervisor bundle from the pinned AWF release, grants the runner user scoped access to /dev/kvm , and starts AWF with the preview runtime flags.

The default guest size is 2 vCPUs and 4096 MiB. Cloud Hypervisor and NVX share compiler-managed KVM permission setup: verify that /dev/kvm exists and is a character device, grant only the runner UID read/write access through an ACL, and verify both effective access and the scoped ACL entry. Setup fails closed with separate diagnostics for a missing device, wrong device type, ACL setup failure, or access verification failure.

These device ACLs are discarded when the ephemeral GitHub-hosted runner is torn down; setup does not change device ownership or grant all users access. Cloud Hypervisor is incompatible with: runner.topology: arc-dind self-hosted, non-Ubuntu, or non-x86_64 runners tools.github.mode: gh-proxy sandbox.agent.allow-host-ports GitHub Actions services with published ports enclaves If the runner does not meet these requirements, omit the runtime to use Docker.

NVX (preview) Section titled “NVX (preview)” NVX runs the agent in AWF’s fail-closed, one-shot microVM runtime. It requires AWF v0.28.49 or newer and a Linux x86_64 host with non-interactive sudo and effective UID 0 for AWF, a /dev/kvm character device, cgroup v2 cpu , memory , and pids controllers, and seccomp kill_process support. Generated preflight grants and verifies scoped KVM access using the same setup as Cloud Hypervisor; the runner user does not need pre-existing device permissions.

It checks the remaining host requirements and fails the job with an actionable diagnostic; NVX never falls back to Docker or Cloud Hypervisor. Declare the runtime to use secure NVX defaults: --- on : workflow_dispatch : # A custom provisioning job must be listed in on.needs. needs : [ build_nvx_artifacts ] sandbox : agent : id : awf runtime : nvx --- Run the workload in the pre-provisioned NVX guest. The defaults expect the workload-specific guest layer and the five trusted assets under ${{ runner.temp }}/nvx/ ( guest-layer , openvmm , vmlinux , initramfs.cpio.gz , and the manifest and Sigstore bundle).

Download and extract the trusted assets from the same pinned AWF release used by the workflow, then build the guest layer before the generated preflight step. The manifest and bundle are verified offline with gh attestation verify ; hashes alone are not accepted. Setup stages the verified files root-owned and read-only, and removes the staging directory after agent execution. Install these host packages before pre-agent setup: acl bubblewrap e2fsprogs erofs-utils jq nftables uidmap .

The required host tools are resolved only from /usr/sbin , /usr/bin , /sbin , or /bin . The compiler selects the musl-compatible Copilot package for NVX guests, downloads the release’s checksum-verified linuxmusl artifact alongside the host CLI, and exports only that guest variant. Workflows do not configure or detect the guest libc ABI. Other sandbox.agent.nvx fields optionally override paths, mount policy, resource limits, and working directory.

Preview mode, strict network isolation, and the API proxy always remain enabled. The compiler stages its Node.js runtime, harness, compiler-selected engine CLI, MCP CLI wrappers, and selected agent inputs under a temporary .gh-aw-nvx directory in the workspace. Only the selected native MCP configuration file under the compiler runtime directory is exported; Copilot’s home configuration uses AWF’s credential-filtered guest home layer.

Other dynamically linked Linux executables include their loader and shared libraries, so glibc-based runner tools can run in musl-based guest layers. Setup installs patchelf on the Ubuntu host if needed and relocates those staged executables to their guest paths, preserving Node/Bun subprocess execution. The guest uses /workspace/.gh-aw-nvx rather than host runner paths. An always-running collection step restores only allowlisted guest artifa

The rest of this page is on the live site.