Document agent runtime selection and troubleshooting

.github/aw/agent-runtime-instructions.md

@@ -0,0 +1,51 @@
+---
+description: Choose and configure agent runtimes for GitHub Agentic Workflows.
+disable-model-invocation: true
+---
+
+# Agent Runtime Instructions
+
+Use these instructions when creating or updating workflows that mention Docker, gVisor, Docker sbx, ARC DinD, self-hosted runners, or `sandbox.agent.runtime-install`.
+
+## Runtime fields
+
+- Omit `sandbox.agent.runtime` for the default Docker agent runtime.
+- Set `sandbox.agent.runtime: gvisor` only when the runner has a local Docker daemon and can install or already has `runsc`.
+- Set `sandbox.agent.runtime: docker-sbx` only when the runner supports KVM-backed microVMs.
+- Do not set `sandbox.agent.runtime: docker`; Docker is selected by omitting the field.
+- Do not set `sandbox.agent.runtime: sbx`; `sbx` is only a bounded-query runtime name.
+- Set `runner.topology: arc-dind` for ARC or equivalent Kubernetes runners that use a Docker-in-Docker sidecar. This is a runner topology, not an agent runtime.
+
+## Compatibility
+
+- Do not combine `runner.topology: arc-dind` with `sandbox.agent.runtime: gvisor` or `sandbox.agent.runtime: docker-sbx`.
+- ARC DinD workflows must be rootless: do not add `sudo`, `apt-get install`, or other host package bootstrap steps.
+- Docker sbx requires KVM and normally does not work on ARC DinD because the sbx daemon must run on the runner host.
+
+## `runtime-install`
+
+- `sandbox.agent.runtime-install` defaults to `true` for gVisor and Docker sbx provisioning.
+- Set `runtime-install: false` only when the runner image or pod is pre-provisioned with the runtime and required daemon or policy.
+- When any imported workflow sets `runtime-install: false`, false wins during import merging.
+- With `runtime-install: false`, gh-aw skips generated runtime checks and setup, so the runner must already satisfy those prerequisites.
+
+## gVisor guidance
+
+- gVisor uses `runsc` for the agent container while AWF infrastructure containers continue to use Docker.
+- The generated gVisor installer may use `sudo`, but do not set `sandbox.agent.sudo: true` merely for gVisor.
+- Use gVisor when stronger kernel isolation is needed and the workload is compatible with gVisor syscall behavior.
+
+## Docker sbx guidance
+
+- Docker sbx runs the agent in a KVM-backed microVM and requires a KVM-capable Linux runner.
+- With runtime installation enabled, set `sandbox.agent.sudo: true` because gh-aw installs `docker-sbx`, adjusts `/dev/kvm`, starts the sbx daemon, authenticates CLIs, pulls the template, and runs a smoke test.
+- Docker sbx requires both `DOCKER_USERNAME` and `DOCKER_PAT` Actions secrets. `DOCKER_PAT` must be a Docker Hub personal access token that can authenticate Docker Hub pulls for the sandbox template.
+- `DOCKER_USERNAME` and `DOCKER_PAT` remain required even with `runtime-install: false`, because compiled workflows refresh sbx credentials immediately before agent execution.
+- Do not use Docker sbx for workflows triggered from untrusted forks unless the trigger and credential model safely provide those secrets.
+
+## ARC DinD guidance
+
+- Use `runner.topology: arc-dind` when `DOCKER_HOST` points to a DinD sidecar such as `tcp://localhost:2375` or `tcp://dind:2375`.
+- Ensure the runner container and DinD sidecar share `/home/runner/_work`.
+- Use a daemon-visible tool cache path such as `/tmp/gh-aw/tool-cache`, not `/opt/hostedtoolcache`.
+- If the Docker socket is bind-mounted at a nonstandard path, set `GH_AW_DOCKER_SOCK_PATH`. Set `GH_AW_DOCKER_SOCK_GID` only when group detection with `stat` fails.

.github/aw/create-agentic-workflow.md

@@ -29,6 +29,7 @@ Load these topic files only when relevant:
 - [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-instructions.md](agent-runtime-instructions.md) when choosing or debugging Docker, gVisor, Docker sbx, ARC DinD, self-hosted runners, or `sandbox.agent.runtime-install`
 
 ## Modes
 

.github/aw/syntax-agentic.md

@@ -315,7 +315,8 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor
     ```
 
   - **`sandbox.agent.sudo`** (boolean) controls whether AWF runs in root mode. Default is `false`: AWF runs rootless in network-isolation egress mode (`--network-isolation`), with MCP sidecars attached as bridge containers on the internal `awf-net` network. Set `sudo: true` for the legacy root mode; in strict mode explicit `sudo: true` is an error (warning otherwise).
-  - **`sandbox.agent.runtime`** (string) selects an extra-isolation container runtime for the agent: `gvisor` (runs under gVisor's `runsc` for kernel-level isolation) or `docker-sbx` (Docker sbx microVM with KVM hypervisor-level isolation; needs `DOCKER_PAT`/`DOCKER_USERNAME` secrets and a KVM-capable runner). Both require `sudo: true` and are incompatible with `runner.topology: arc-dind`.
+  - **`sandbox.agent.runtime`** (string) selects an extra-isolation container runtime for the agent: `gvisor` (runs under gVisor's `runsc` for kernel-level isolation) or `docker-sbx` (Docker sbx microVM with KVM hypervisor-level isolation). Both are incompatible with `runner.topology: arc-dind`. gVisor's generated host installer uses `sudo`, but `sandbox.agent.sudo` should remain false. Docker sbx requires `sudo: true`, `DOCKER_PAT`/`DOCKER_USERNAME` secrets, and a KVM-capable runner when runtime installation is enabled.
+  - **`sandbox.agent.runtime-install`** (boolean) controls generated gVisor or Docker sbx provisioning and defaults to `true`. Set it to `false` only when the runner is pre-provisioned; Docker sbx credential refresh still runs. False wins when imported workflows merge this field. See [agent-runtime-instructions.md](agent-runtime-instructions.md) for requirements and troubleshooting.
   - **Strict mode**: `sandbox.agent` blocks without an explicit `id: awf` are rejected in strict mode. Any non-nil, non-disabled agent config without `id`/`type` defaults to AWF at runtime.
 
 - **`tools:`** - Tool configuration for the coding agent (`github`, `agentic-workflows`, `edit`, `web-fetch`, `web-search`, `bash`, `playwright`, custom MCP server names, plus `timeout`/`startup-timeout`/`cli-proxy`). See [syntax-tools-imports.md](syntax-tools-imports.md#tool-configuration) for the full schema (GitHub `mode`/`toolsets`/integrity fields, bash allowlist decision rule, Playwright CLI mode).

.github/aw/update-agentic-workflow.md

@@ -22,6 +22,7 @@ Load these additional files only when relevant:
 - [visual-regression.md](visual-regression.md)
 - [serena-tool.md](serena-tool.md)
 - [linter-workflows.md](linter-workflows.md)
+- [agent-runtime-instructions.md](agent-runtime-instructions.md) for changes involving Docker, gVisor, Docker sbx, ARC DinD, self-hosted runners, or `sandbox.agent.runtime-install`
 
 ## Scope
 

.github/skills/agentic-workflows/SKILL.md

@@ -16,6 +16,7 @@ Repository overlay (optional):
 Read only the files you need:
 Load these files from `github/gh-aw` (they are not available locally).
 - `.github/aw/action-container-substitutions.md`
+- `.github/aw/agent-runtime-instructions.md`
 - `.github/aw/agentic-chat.md`
 - `.github/aw/agentic-workflows-mcp.md`
 - `.github/aw/asciicharts.md`

docs/astro.config.mjs

@@ -441,6 +441,7 @@ export default defineConfig({
 						{ label: 'Safe Outputs (Ephemerals)', link: '/reference/ephemerals/' },
 						{ label: 'Safe Outputs (Footers)', link: '/reference/footers/' },
 						{ label: 'Sandbox', link: '/reference/sandbox/' },
+						{ label: 'Sandbox (Agent Runtimes)', link: '/reference/agent-runtimes/' },
 						{ label: 'Self-Hosted Runners', link: '/reference/self-hosted-runners/' },
 						{ label: 'Sandbox (MCP Gateway)', link: '/reference/mcp-gateway/' },
 						{ label: 'Sandbox (Network Access)', link: '/reference/network/' },