Document mandatory sudo requirement for self-hosted agentic workflows

[Copilot]

Self-hosted runs were expected to work without privilege escalation, but the current agent job security model depends on root-level operations. This PR clarifies that requirement in the self-hosted runner docs and explains why allowPrivilegeEscalation: false configurations are not supported for agentic workflows.

• Docs update: self-hosted runner requirement

  • Added an explicit warning to guides/self-hosted-runners.md that self-hosted runners must permit sudo for agentic workflows.

• Security rationale clarified (not optional behavior)

  • Documented that AWF enforces host-level egress controls by programming Linux iptables in the DOCKER-USER chain (root UID required).
  • Clarified that container-level controls (iptables in-container, Squid ACLs, capability drops) are defense-in-depth layers and do not replace the host boundary.

• Unsupported mode explicitly called out

  • Stated that a non-sudo mode is not available, including ARC setups with allowPrivilegeEscalation: false.

> [!WARNING]
> Self-hosted runners must allow `sudo` for agentic workflows...
> AWF applies host-level `iptables` rules to the Linux kernel
> `DOCKER-USER` chain ... This outer security boundary requires root UID.

• screenshot
  • Updated docs page: https://github.com/user-attachments/assets/38c00f8e-905e-4e0f-8667-6d88387fccc4

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro dev --host 127.0.0.1 --port 4321 odules/npm/node_modules/@npmcli/run-script/lib/node-gyp-bin/node (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Support execution on self-hosted without sudo</issue_title>
<issue_description>When executing gh aw compile Workflows on self-hosted GitHub Runners fails currently on the Install GitHub Copilot CLI task of the agent Job, if the Runners do not permit escalation to root user.
This is because the script at https://github.com/github/gh-aw/blob/main/actions/setup/sh/install_copilot_cli.sh blindly runs sudo commands without checking existing directory permissions or user, and copies binaries into root-owned directories such as /usr/local/bin.

Please change the GH AW workflow compilation to support execution on a self-hosted Runner that does not permit sudo commands e.g. Actions Runner Controller (ARC) with allowPrivilegeEscalation: false</issue_description>

<agent_instructions>Document that self-hosted runners require sudo permission for agentic workflows

Read the Scout research comment on issue #18188 for full context.

Add documentation explaining that GH-AW agentic workflows require sudo on self-hosted runners. This is a deliberate security requirement, not a convenience shortcut.

What to document:

Why sudo is required: AWF (Agentic Workflow Firewall) uses host-level iptables to manipulate the Linux kernel's DOCKER-USER chain, providing defense-in-depth network egress filtering for all containers on the AWF bridge network. This requires root UID. Container-level iptables, Squid proxy ACLs, and capability drops provide additional layers, but host-level filtering is the outermost security boundary and we do not offer a mode without it.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@dsyme /scout research the codebase and determine all the requirements we would have of a self hosted runner to make it viable to use it to run GH-AW workflows, and what would need to be done to also allow "allowPrivilegeEscalation: false" for those runners. Be very precise and do a detailed, careful analysis. Also explain how we might test that we don't pick up additional requirements unexpectedly

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

• Fixes Support execution on self-hosted without sudo #18188

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR documents the mandatory sudo requirement for self-hosted runners in agentic workflows, clarifying that AWF requires root-level access for host-level iptables rules and explicitly stating that non-sudo configurations are not supported.

Changes:

• Added a WARNING block to the self-hosted runners guide explaining the sudo requirement and its security rationale
• Documented that AWF enforces network egress filtering via host-level iptables rules on the DOCKER-USER chain, requiring root UID
• Explicitly called out that ARC configurations with allowPrivilegeEscalation: false are not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.