Text of github.github.com › gh-aw › reference › self-hosted-runners 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

Self-Hosted Runners | GitHub Agentic Workflows

Skip to main content Self-Hosted Runners Use the runs-on frontmatter field to target a self-hosted runner instead of the default ubuntu-latest . Runners must be Linux with Docker support. macOS and Windows are not supported. To enforce self-hosted runners for every generated job, set require_self_hosted_runners in .github/workflows/aw.json or pass --require-self-hosted-runners for a one-off compile: .github/workflows/aw.json { "require_self_hosted_runners" : true } The compiler checks all generated jobs, including framework and safe-output jobs.

Each must use the self-hosted label or a runner group. The GH_AW_REQUIRE_SELF_HOSTED_RUNNERS=true compiler environment variable also enables this enforcement. Host isolation checklist Section titled “Host isolation checklist” A self-hosted runner processes potentially hostile repository content even in private or internal repositories. The agent sandbox does not establish that the underlying host is clean. An ephemeral runner registration accepts one job, but re-registering on reused hardware, a reused VM disk, or persistent Kubernetes volumes can preserve an earlier job’s compromise.

Before admitting untrusted work: Provision a clean, disposable VM or equivalent isolated environment for each job and destroy its writable state afterward. For ARC, include the DinD daemon’s state and mounted volumes; replacing only the runner pod is insufficient when those persist. Separate trusted release, publish, and deployment jobs from untrusted execution using distinct runner groups and infrastructure. Restrict group access to the intended repositories and workflows; do not share writable disks, Docker daemons, or credentials between trust domains.

Isolate or discard local npm/pip caches, build directories, tool caches, installed binaries, home directories, and Docker images/volumes. Audit Actions dependency-cache restores and writers separately from cache-memory ; service-side cache restrictions do not protect persistent host caches. Restrict Docker socket access to trusted runner components, never make the socket world-accessible, and prevent untrusted workloads from reaching other jobs’ daemons.

Limit host/internal-network and cloud metadata access independently of the agent’s firewall. Remove ambient Git, cloud, registry, SSH, and Kubernetes credentials from the host; grant only job-scoped credentials to the components that need them. Verify teardown after cancelled or failed jobs, not just successful runs. Runner labels, runner-group selection, and require_self_hosted_runners route or constrain jobs; they do not prove host ephemerality or enforce this checklist.

Host provisioning, access controls, and lifecycle verification remain operator responsibilities. Self-hosted runners may require sudo depending on the selected engine and configuration. For the default GitHub Copilot engine, there are two distinct sudo considerations: AWF (Agentic Workflow Firewall) : Runs rootless in the default network-isolation mode. Egress is enforced 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.

No sudo and no NET_ADMIN are required on the runner for AWF in this mode. Container-level iptables , Squid proxy ACLs, and capability drops provide defense in depth, all managed inside the Docker daemon’s domain. Copilot CLI and threat-detect installation : Root and passwordless-sudo runners install these binaries to /usr/local/bin . Rootless installation uses the job-scoped $RUNNER_TEMP/gh-aw/bin directory without sudo .

Unprivileged CLI installation Section titled “Unprivileged CLI installation” Set runner.installation: rootless for a native Linux runner without sudo or write access to /usr/local/bin : --- on : issues runs-on : linux64-selfhosted runner : installation : rootless --- Triage this issue. This setting applies to the generated Copilot CLI and threat-detect installers in the agent and detection jobs, including when safe-outputs.threat-detection.runs-on selects a different runner.

Rootless installs use $RUNNER_TEMP/gh-aw/bin , a job-scoped directory that AWF mounts read-only, and publish it through GITHUB_PATH . This protects host-executed binaries from sandbox changes. The directory must be writable during setup. External threat detection stages the verified detector there so the sandbox can resolve it independently of its home directory. Release pins, checksum verification, HTTPS requirements, platform checks, and Copilot’s trusted toolcache policy remain unchanged.

Omitting runner.installation preserves the existing defaults. Explicit privileged selects the native sudo-based installation and is rejected with runner.topology: arc-dind . Installation privilege does not change AWF runtime privileges or enable split-filesystem handling. Leave runner.topology unset for a native runner; use arc-dind only for a split runner/daemon filesystem. Other engines, custom steps, and privileged runtime profiles may still require sudo .

Recompile with gh aw compile after changing the setting; do not edit the generated lock file. When runner.installation is omitted, native installers automatically choose rootless mode if the runner is neither root nor able to run sudo -n true ; root and passwordless-sudo runners retain privileged installation. ARC/DinD explicitly selects rootless mode even when sudo is available. engine.command skips standard Copilot installation only for the primary agent.

External Copilot threat detection still installs and uses the standard copilot executable; it does not run the primary agent’s custom command. A preinstalled executable on PATH does not skip either installer or its privilege checks. Rootless installation cannot repair root-owned state from previous privileged AWF runs. If preparing ~/.copilot fails, installation stops with an ownership-repair diagnostic. Before retrying, a runner administrator must restore ownership of that directory and its contents to the runner’s UID and GID and make it writable.

Installers clean only their own staging directories, not shared /tmp/awf-*-chroot-home or /tmp/awf-chroot-* directories that may belong to active jobs. A runner administrator must remove confirmed stale directories before the runner is reused. Runner HTTP proxy settings Section titled “Runner HTTP proxy settings” On runners that require an HTTP proxy for outbound access, configure HTTP_PROXY , HTTPS_PROXY , and NO_PROXY in the runner environment before the CLI proxy and MCP gateway start.

Both containers inherit defined values, including the lowercase forms http_proxy , https_proxy , and no_proxy . Explicit MCP gateway environment settings take precedence over inherited values. The MCP gateway extends inherited proxy exclusions for its internal backend hosts so local MCP traffic remains reachable. If you explicitly override the gateway’s NO_PROXY or no_proxy , include the internal hosts host.docker.internal and awf-enclave-mcp along with your organization’s exclusions.

CLI proxy startup checks upstream GitHub API connectivity before reporting readiness. A passing local health check alone does not establish upstream connectivity. Proxy values are redacted from CLI proxy and MCP gateway diagnostics. ARC with Docker-in-Docker (DinD) Section titled “ARC with Docker-in-Docker (DinD)” For a complete ARC DinD setup walkthrough for the gh-aw Copilot engine, see How to run the gh-aw Copilot engine on ARC with Docker-in-Docker .

Actions Runner Controller (ARC) deployments that use a Docker-in-Docker sidecar split the runner container and the Docker daemon container across separate filesystems. Set runner.topology: arc-dind in workflow frontmatter for this environment. Compiled workflows emit a runtime probe that inspects DOCKER_HOST . Any tcp:// endpoint (for example tcp://localhost:2375 , tcp://dind:2375 , or tcp://172.30.0.5:2375 ) is treated as ARC DinD, so ensure DOCKER_HOST points to t

The rest of this page is on the live site.