How to run the gh-aw Copilot engine on ARC with Docker-in-Docker | GitHub Agentic Workflows
Skip to main content How to run the gh-aw Copilot engine on ARC with Docker-in-Docker Use this guide to configure the gh-aw Copilot engine on an Actions Runner Controller (ARC) runner scale set with Docker-in-Docker (DinD). This engine runs Copilot CLI inside an Actions job; it is not the separate GitHub Copilot coding-agent service. For the full self-hosted runner reference (including runs-on formats, framework job runners, Docker socket overrides, and GHES), see Self-Hosted Runners .
Prerequisites Section titled “Prerequisites” Before starting, confirm you have a Kubernetes cluster, helm and kubectl installed, and credentials for runner registration (a GitHub PAT or GitHub App credentials). The runner needs working Docker and Compose access, Node.js for framework scripts, and separate Copilot inference credentials/licensing/policy authorization. See component prerequisites . The example chart commands do not pin or certify a chart version; validate and pin the chart, runner image, and pod configuration for your cluster.
1. Install the ARC controller Section titled “1. Install the ARC controller” Terminal window helm install arc \ --namespace " arc-system " --create-namespace \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller 2. Create the runner namespace and auth secret Section titled “2. Create the runner namespace and auth secret” Create the namespace and a Kubernetes secret with your runner registration credentials.
You can use either a GitHub PAT or GitHub App credentials: Terminal window kubectl create ns arc-runners # Option A: Personal access token kubectl create secret generic arc-runner-secret \ --namespace=arc-runners \ --from-literal=github_token=<YOUR_PAT> # Option B: GitHub App (recommended for production) kubectl create secret generic arc-runner-secret \ --namespace=arc-runners \ --from-literal=github_app_id=<APP_ID> \ --from-literal=github_app_installation_id=<INSTALL_ID> \ --from-literal=github_app_private_key=<PRIVATE_KEY> See Authenticating to the GitHub API for details on each option.
3. Install a runner scale set in DinD mode Section titled “3. Install a runner scale set in DinD mode” Terminal window helm install " arc-runner-set " \ --namespace " arc-runners " --create-namespace \ --set githubConfigUrl= " https://github.com/<OWNER>/<REPO> " \ --set githubConfigSecret= " arc-runner-secret " \ --set containerMode.type= " dind " \ --set-json ' template.spec.containers=[{ "name": "runner", "image": "ghcr.io/actions/actions-runner:latest", "command": ["/home/runner/run.sh"] }] ' \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set When containerMode.type="dind" is enabled, ARC configures the DinD sidecar in privileged mode by default so the Docker daemon can run.
The runner container does not require privileged: true or NET_ADMIN . If you use a custom pod template, ensure you do not remove the privileged setting on the DinD sidecar. 4. Verify the runner is online Section titled “4. Verify the runner is online” Open https://github.com/<OWNER>/<REPO>/settings/actions/runners (or the organization-level runners page) and confirm the arc-runner-set runner is online. 5. Target the runner set from a workflow Section titled “5.
Target the runner set from a workflow” Set your workflow frontmatter to use the runner scale set label and ARC DinD topology: --- on : issues runs-on : arc-runner-set runner : topology : arc-dind --- runner.topology: arc-dind is required so compiled workflows enable ARC DinD split-filesystem handling (a shared runner/daemon workspace root, Docker-daemon-visible mount paths, and ARC-specific sandbox setup). The compiler handles its staging and default network isolation, but the operator must provide shared volumes, Docker socket access for the MCP gateway, and deployment-specific connectivity and policy configuration.
After editing the frontmatter, recompile the lock file: Terminal window gh aw compile Commit both the .md workflow file and the generated .lock.yml file. 6. How it works Section titled “6. How it works” When compiled workflows detect a tcp:// value in DOCKER_HOST (set automatically by ARC DinD), a runtime probe activates ARC DinD handling: Sysroot staging — AWF stages the release-tagged build-tools image’s system binaries and libraries into a Docker named volume for the agent chroot.
It does not make the runner’s private /usr , /lib , /bin , or /sbin visible to the daemon. Runner-installed tools still need daemon-visible shared paths. Workspace mount — the checked-out repository at GITHUB_WORKSPACE is explicitly mounted into the agent container. Both runner and daemon can see it because ARC DinD shares the /home/runner/_work/ volume. Chroot identity — the runner’s UID/GID and home directory are patched into the AWF config so the agent runs with the correct identity inside the chroot.
Artifact consolidation — agent output files are consolidated under ${{ runner.temp }}/gh-aw/ before upload so downstream jobs (detection, safe-outputs) can find them. Network isolation — AWF enforces egress via Docker network topology: an internal Docker network ( awf-net ) with no internet route and a dual-homed Squid proxy as the sole egress path. The runner container issues Docker API commands to the DinD sidecar daemon; the daemon creates the networks and manages all traffic enforcement.
No host iptables rules are applied from the runner container. Network requirements Section titled “Network requirements” ARC DinD runners need outbound HTTPS (port 443) access from the runner pod. If your cluster uses Kubernetes NetworkPolicies or a service mesh, ensure the runner pod can reach: Destination Purpose github.com (or your GHES instance) Git clone, API calls, Actions runtime api.githubcopilot.com (or your enterprise Copilot endpoint) Copilot engine communication ghcr.io and pkg-containers.githubusercontent.com Pull MCP gateway and AWF container images Domains in your workflow’s network.allowed list Agent egress (npm registries, PyPI, etc.) Intra-pod communication Section titled “Intra-pod communication” The runner container communicates with the DinD sidecar over DOCKER_HOST (typically tcp://localhost:2375 ).
This is intra-pod traffic over the loopback interface — no NetworkPolicy is needed for it. AWF creates Docker networks inside the DinD daemon for sandbox isolation. All agent egress is routed through a Squid proxy container on the awf-net Docker network. This is internal to the DinD daemon and invisible to Kubernetes networking. What is NOT required Section titled “What is NOT required” NET_ADMIN capability — AWF uses Docker network topology for egress enforcement, not host iptables . iptables binary — not used in network-isolation mode.
Log lines mentioning iptables are a legacy artifact from the privileged docker-sudo-iptables runtime profile and can be ignored. Host network mode — the runner pod uses standard pod networking. Do not set hostNetwork: true . Privileged runner container — only the DinD sidecar needs privileged: true . The runner container runs unprivileged. 7. Required versions Section titled “7. Required versions” These are historical component-specific fix floors, not an end-to-end support matrix.
Use a reviewed compiler release and its matching AWF pin, then recompile; meeting these floors does not certify an arbitrary newer release, GHES version, or ARC chart: Component Minimum version Why gh-aw v0.82.8 Includes ARC DinD workspace/detection fixes and the MCP gateway Docker socket access fix. AWF ( agentic-workflow-firewall ) v0.27.22 Includes DinD squid log permission fixes. The compiler’s narrower ARC startup gate is AWF v0.27.20+ for sysroot/chroot mount fixes; the walkthrough’s v0.27.22 floor includes subsequent log-permission fixes.
See version constants and ARC validation . If you’re on gh-aw v0.82.5 – v0.82.7 , upgrade and recompile before using this g
The rest of this page is on the live site.