Document agent runtime selection and troubleshooting by lpcox · Pull Request #51427 · github/gh-aw

lpcox · 2026-08-08T17:40:06Z

Summary

add a runtime selection reference for Docker, gVisor, Docker sbx, and ARC DinD
document frontmatter values, runtime-install, runner prerequisites, isolation tradeoffs, and incompatibilities
provide dependency-ordered troubleshooting for setup, daemon, authentication, mount, tool-cache, and proxy failures
distinguish main-agent runtime values from ARC topology and bounded-query runtime names
add the page to the Reference navigation
route workflow create/update agents to the guide when runtime or runner topology decisions are relevant
correct the authoring syntax summary for gVisor sudo behavior and runtime-install

Validation

node --check docs/astro.config.mjs
parsed the page frontmatter with Ruby YAML
git diff --check

The full Astro build could not start because the configured npm feed returned 404 for vite@8.1.0.

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 12.4 AIC · ⌖ 5.26 AIC · ⊞ 6.1K · ◷
_{Comment /souschef to run again}

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a9759f72-8612-45b7-9a94-e1f968e96ef4

Copilot

Pull request overview

Adds a reference for selecting, configuring, and troubleshooting agent runtimes.

Changes:

Documents Docker, gVisor, Docker sbx, and ARC DinD.
Clarifies runtime fields, prerequisites, tradeoffs, and troubleshooting.
Adds the reference page to navigation.

Show a summary per file

File	Description
`docs/src/content/docs/reference/agent-runtimes.md`	Adds the runtime reference.
`docs/astro.config.mjs`	Adds navigation for the new page.

Review details

Tip

Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Files reviewed: 5/5 changed files
Comments generated: 2
Review effort level: Balanced

+
+**Compilation rejects `sudo` or `apt-get install`:** Move system packages into the runner image or DinD image. ARC DinD workflows are validated as rootless and must not bootstrap host packages during the job.
+
+**`Docker daemon is not accessible` from the MCP gateway:** If a Unix socket is mounted at a nonstandard path, set `GH_AW_DOCKER_SOCK_PATH` and `GH_AW_DOCKER_SOCK_GID` in the runner pod. Both values are required. See [Docker socket override for split-daemon topologies](/gh-aw/reference/self-hosted-runners/#docker-socket-override-for-split-daemon-topologies).


+
+**`KVM kernel module is not loaded` or `/dev/kvm is missing`:** The runner does not provide hardware virtualization. Enable nested virtualization and pass `/dev/kvm` through to the runner, or select gVisor or Docker. Frontmatter cannot add KVM capability. With `runtime-install: false`, this generated check is skipped, but sbx execution still fails if KVM is unavailable.
+
+**Permission denied for `/dev/kvm`:** Confirm the runner can execute passwordless `sudo` and that its security policy permits the generated `chmod 666 /dev/kvm`. If that policy is unacceptable, do not use Docker sbx.


github-actions · 2026-08-08T17:49:55Z

Visual Regression Check - Unable to Complete

Attempted to load the docs server at (host.docker.internal/redacted) via playwright-cli to capture mobile/tablet/desktop screenshots, but every navigation attempt returned HTTP 403 Forbidden (Page Title: ERROR: The requested URL could not be retrieved). This occurred consistently across multiple retries, indicating the sandboxed browser could not reach the docs server (likely a network/proxy restriction rather than an app issue). No screenshots or accessibility snapshots could be captured.

Page	Viewport	Screenshot Status
Home	Mobile (375x812)	error (403 Forbidden)
Home	Tablet (768x1024)	not attempted (blocked)
Home	Desktop (1440x900)	not attempted (blocked)

No visual comparison or accessibility review was possible this run.

Warning

Firewall blocked 6 domains

The following domains were blocked by the firewall during workflow execution:

accounts.google.com
android.clients.google.com
clients2.google.com
host.docker.internal
safebrowsingohttpgateway.googleapis.com
www.google.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "host.docker.internal"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

Generated by 👁️ Visual Regression Checker for #51427 · auto · 27 AIC · ⌖ 2.24 AIC · ⊞ 6.6K · ◷

lpcox · 2026-08-08T17:52:10Z

@copilot address review feedback

gh-aw-bot · 2026-08-08T17:56:40Z

@copilot Quick triage nudge for this PR.

Please refresh the branch if GitHub can update it cleanly, address the latest review feedback, and run the pr-finisher skill before handing this back to maintainers.

Open items (newest first):

Reviewer follow-up requested by the PR author in the latest comment: Document agent runtime selection and troubleshooting #51427 (comment)
No failed checks listed in the compact candidate report.

Run: https://github.com/github/gh-aw/actions/runs/31270434674

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 12.4 AIC · ⌖ 5.26 AIC · ⊞ 6.1K · ◷
_{Comment /souschef to run again}

pelikhan · 2026-08-08T18:00:41Z

 - [report.md](report.md) for reporting output structure and recurring report lifecycle
 - [release-workflow.md](release-workflow.md) for release workflows that build, test, publish a GitHub release, and generate release highlights
 - [linter-workflows.md](linter-workflows.md) for mining, refining, or applying custom linter rules
+- [Agent Runtime Selection](../../docs/src/content/docs/reference/agent-runtimes.md) when choosing or debugging Docker, gVisor, Docker sbx, ARC DinD, self-hosted runners, or `sandbox.agent.runtime-install`


@copilot create a dedicated instructions file, do not link to "human docs"

Addressed in 1e46777: added .github/aw/agent-runtime-instructions.md and updated the workflow authoring prompts to reference that dedicated agent instruction file instead of the published docs page.

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Copilot · 2026-08-08T18:01:45Z

@copilot address review feedback

Addressed in ad48714: clarified /dev/kvm troubleshooting for both runtime-install modes and updated the ARC DinD socket guidance so GH_AW_DOCKER_SOCK_GID is only needed when group detection fails.

pelikhan · 2026-08-08T18:02:05Z

@copilot document DOCKER_PAT requirement for docker_sbx

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-08-08T18:24:42Z

@copilot Quick triage nudge for this PR.

Please refresh the branch if GitHub can update it cleanly, address the latest review feedback, and run the pr-finisher skill before handing this back to mai...

Ran pr-finisher and addressed the open items in 1e46777. Local validation passed where relevant; make lint still reports unrelated existing testifylint issues in pkg/parser/import_schema_validation_input_type_test.go.

@copilot document DOCKER_PAT requirement for docker_sbx

Addressed in 1e46777: documented that Docker sbx requires DOCKER_PAT even with runtime-install: false, and captured the same requirement in the dedicated agent runtime instructions.

docs: explain agent runtime selection

eb1e998

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a9759f72-8612-45b7-9a94-e1f968e96ef4

Copilot AI balanced review requested due to automatic review settings August 8, 2026 17:40

Copilot started reviewing on behalf of lpcox August 8, 2026 17:40 View session

docs: route agents to runtime guidance

fb644b0

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a9759f72-8612-45b7-9a94-e1f968e96ef4

Copilot AI reviewed Aug 8, 2026

View reviewed changes

Copilot started work on behalf of lpcox August 8, 2026 17:52 View session

Merge branch 'main' into docs-agent-runtime-selection

faa7530

github-actions Bot mentioned this pull request Aug 8, 2026

[pr-sous-chef] PR Sous Chef run report (2026-08-08T00:07:20Z) #51239

Closed

pelikhan reviewed Aug 8, 2026

View reviewed changes

docs: address runtime review feedback

ad48714

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Copilot finished work on behalf of lpcox August 8, 2026 18:02

Copilot started work on behalf of pelikhan August 8, 2026 18:02 View session

docs: add agent runtime instructions

1e46777

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan August 8, 2026 18:25

Copilot finished work on behalf of pelikhan August 8, 2026 18:25

Merge branch 'main' into docs-agent-runtime-selection

ae43049

pelikhan merged commit 8d08af3 into main Aug 8, 2026
4 checks passed

pelikhan deleted the docs-agent-runtime-selection branch August 8, 2026 18:26

github-actions Bot mentioned this pull request Aug 8, 2026

[aw] Visual Regression Checker is missing required data #51440

Closed

Navigation Menu

Uh oh!

Document agent runtime selection and troubleshooting - #51427

Document agent runtime selection and troubleshooting#51427
pelikhan merged 6 commits into
mainfrom
docs-agent-runtime-selection

lpcox commented Aug 8, 2026 •

edited by github-actions Bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Aug 8, 2026

Uh oh!

lpcox commented Aug 8, 2026

Uh oh!

gh-aw-bot commented Aug 8, 2026

Uh oh!

pelikhan Aug 8, 2026

Uh oh!

Copilot AI Aug 8, 2026

Uh oh!

Copilot AI commented Aug 8, 2026

Uh oh!

pelikhan commented Aug 8, 2026

Uh oh!

Copilot AI commented Aug 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		Compilation rejects `sudo` or `apt-get install`: Move system packages into the runner image or DinD image. ARC DinD workflows are validated as rootless and must not bootstrap host packages during the job.

		`Docker daemon is not accessible` from the MCP gateway: If a Unix socket is mounted at a nonstandard path, set `GH_AW_DOCKER_SOCK_PATH` and `GH_AW_DOCKER_SOCK_GID` in the runner pod. Both values are required. See [Docker socket override for split-daemon topologies](/gh-aw/reference/self-hosted-runners/#docker-socket-override-for-split-daemon-topologies).


		`KVM kernel module is not loaded` or `/dev/kvm is missing`: The runner does not provide hardware virtualization. Enable nested virtualization and pass `/dev/kvm` through to the runner, or select gVisor or Docker. Frontmatter cannot add KVM capability. With `runtime-install: false`, this generated check is skipped, but sbx execution still fails if KVM is unavailable.

		Permission denied for `/dev/kvm`: Confirm the runner can execute passwordless `sudo` and that its security policy permits the generated `chmod 666 /dev/kvm`. If that policy is unacceptable, do not use Docker sbx.

Uh oh!

Conversation

lpcox commented Aug 8, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

github-actions Bot commented Aug 8, 2026

Visual Regression Check - Unable to Complete

Uh oh!

lpcox commented Aug 8, 2026

Uh oh!

gh-aw-bot commented Aug 8, 2026

Uh oh!

pelikhan Aug 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Aug 8, 2026

Uh oh!

pelikhan commented Aug 8, 2026

Uh oh!

Copilot AI commented Aug 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lpcox commented Aug 8, 2026 •

edited by github-actions Bot

Loading

Copilot AI commented Aug 8, 2026 •

edited

Loading