[workshop] Add node: Running on Actions Runner Controller (ARC) with Docker-in-Docker

workshop/24-self-hosted-runners.md

@@ -88,6 +88,8 @@ registration settings (Settings → Actions → Runners).
 
 Running in an enterprise environment? See [Side Quest: Self-Hosted Runner Infrastructure Deep Dive](side-quest-24-01-runner-infrastructure.md) for guidance on [ephemeral](https://github.github.com/gh-aw/reference/ephemerals/) and JIT runners, proxy configuration, and [network](https://github.github.com/gh-aw/reference/network/) isolation for air-gapped environments.
 
+Running on a Kubernetes-hosted runner fleet managed by Actions Runner Controller (ARC)? See [Side Quest: Running on Actions Runner Controller (ARC) with Docker-in-Docker](side-quest-24-02-arc-dind-kubernetes.md) for the frontmatter setting agentic workflows require on ARC.
+
 ## :pencil2: Exercise: Compile and commit
 
 Recompile after editing the frontmatter, then commit both files:

workshop/README.md

@@ -104,6 +104,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [How A/B Experiment Round-Robin Assignment Works](side-quest-23-01-ab-roundrobin.md) — deep dive into the five per-run steps gh-aw performs for `experiments:`, first-in-array tie breaking, and worked prediction tables for reading the `experiment` artifact; branches from [Step 23](23-ab-experiments.md).
 - [Audit Reference — Artifacts, Firewall Logs, and Report Contents](side-quest-25-01-audit-reference.md) — detailed breakdown of `gh aw audit` report fields, agent artifact files, ⌖ AIC billing, `firewall.md`, and `network.allow`; branches from [Step 25](25-audit-and-observability.md).
 - [Self-Hosted Runner Infrastructure Deep Dive](side-quest-24-01-runner-infrastructure.md) — enterprise infrastructure primer covering ephemeral and JIT runners, proxy configuration, and network isolation for air-gapped environments; branches from [Step 24](24-self-hosted-runners.md).
+- [Running on Actions Runner Controller (ARC) with Docker-in-Docker](side-quest-24-02-arc-dind-kubernetes.md) — explains why agentic workflows require ARC's Docker-in-Docker mode on Kubernetes-hosted runner fleets and how to set the `runner.topology: arc-dind` frontmatter field; branches from [Step 24](24-self-hosted-runners.md).
 - [Project Future AI Credit Costs with `gh aw forecast`](side-quest-26-01-forecast-costs.md) — full walkthrough of `gh aw forecast`: reading P10/P50/P90 output, using `--period week` and `--days 7`, forecasting all workflows, and deriving a `max-daily-ai-credits` value from the P90 figure; branches from [Step 26](26-manage-costs-and-budgets.md).
 - [Skill Injection Strategies — Hint, Fusion, and Inline](side-quest-29-01-skill-injection-strategies.md) — decision table, code examples, and a practice exercise for the hint, fusion, and inline strategies for wiring a `SKILL.md` into a workflow prompt; branches from [Step 29](29-skills-and-domain-knowledge.md).
 - [Recognizing Common Agentic Workflow Failure Modes](side-quest-22-01-failure-modes.md) — worked examples of empty data, tool error, timeout, and prompt drift failures with a match-the-fix practice exercise; branches from [Step 22](22-error-handling-and-resilience.md).

workshop/side-quest-24-02-arc-dind-kubernetes.md

@@ -0,0 +1,82 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+<!--
+<research-metadata>
+  <focus>Running agentic workflows on Actions Runner Controller (ARC) with Docker-in-Docker (DinD) for Kubernetes-based self-hosted runner fleets, using the runner.topology: arc-dind frontmatter field</focus>
+  <sources>
+    <source>https://github.github.com/gh-aw/reference/arc-dind-copilot-agent/</source>
+    <source>https://github.github.com/gh-aw/reference/self-hosted-runners/</source>
+  </sources>
+  <rationale>The existing self-hosted runner content (Step 24 and its infrastructure deep-dive side quest) covers runner labels, ephemeral/JIT runners, and proxy configuration, but never mentions Kubernetes-based runner fleets managed by Actions Runner Controller — a common enterprise pattern. Learners running Kubernetes-hosted runners have no guidance on the runner.topology: arc-dind field, which is required for agentic workflows to work correctly on ARC. This side quest closes that gap for enterprise learners on Kubernetes infrastructure.</rationale>
+</research-metadata>
+-->
+# Side Quest: Running on Actions Runner Controller (ARC) with Docker-in-Docker
+
+> _If your organisation runs Kubernetes-hosted runners, one frontmatter field is the difference between a working agent and a mysterious failure._
+
+## :dart: What You'll Do
+
+You'll learn what Actions Runner Controller (ARC) is, why it needs Docker-in-Docker (DinD) mode for agentic workflows, and how to set the `runner.topology: arc-dind` frontmatter field so your workflow runs correctly on Kubernetes-managed runners.
+
+## :clipboard: Before You Start
+
+- You completed [Run Your Agentic Workflow on a Self-Hosted Runner](24-self-hosted-runners.md).
+- Your organisation uses Kubernetes to host self-hosted runners (via ARC), rather than standalone VMs.
+- You have access to your cluster or can consult your platform admin.
+
+## Steps
+
+### Understand why ARC needs a special mode
+
+**Actions Runner Controller (ARC)** is a Kubernetes operator that manages self-hosted GitHub Actions runners as pods. Agentic workflows need a Docker daemon to run the agent sandbox, so ARC runner pods must use **Docker-in-Docker (DinD) mode** — a privileged sidecar container running its own Docker daemon alongside the runner container.
+
+> [!NOTE]
+> Kubernetes mode (`containerMode.type="kubernetes"`) works for classic Actions jobs, but it is **not supported** for agentic workflows. Only DinD mode works.
+
+Without the right frontmatter setting, a workflow on an ARC DinD runner can fail confusingly: an empty workspace, a missing Docker socket, or tool-cache warnings. One field fixes all of this.
+
+### Add `runner.topology: arc-dind` to your frontmatter
+
+Open your workflow file and add a `runner:` block alongside your existing `runs-on:` value:
+
+```markdown .github/workflows/daily-status.md
+---
+runs-on: arc-runner-set
+runner:
+  topology: arc-dind
+---
+```
+
+Replace `arc-runner-set` with the label your platform admin assigned to your ARC runner scale set.
+
+`runner.topology: arc-dind` tells the compiler to handle ARC's DinD quirks automatically: sharing system binaries with the Docker daemon over a named volume, mounting your checked-out repository into the agent's sandbox container, matching user identities so file permissions line up, and collecting agent output to a predictable path. You do not need to configure any of this by hand.
+
+### Compile and verify
+
+```bash
+gh aw compile
+```
+
+Commit both the `.md` file and the regenerated `.lock.yml`, then trigger a manual run and confirm it completes on your ARC runner.
+
+> [!TIP]
+> Ask your platform admin to confirm your ARC controller is running in DinD mode (`containerMode.type="dind"`) before troubleshooting further — the two most common blockers are a non-DinD runner and a missing shared work volume.
+
+### Know where to look when something goes wrong
+
+ARC DinD runners write sandbox logs to `$RUNNER_TEMP/gh-aw/sandbox/firewall/logs/`, not the usual `/tmp/gh-aw/` path, because `$RUNNER_TEMP` sits on the volume shared with the Docker daemon. Check `awf.log` there first for sandbox setup and network-isolation details.
+
+> [!NOTE]
+> If your cluster enforces `allowPrivilegeEscalation: false`, the default Copilot CLI installer needs `sudo`, which will be blocked. Ask your admin about installing with the `--rootless` flag in your `copilot-setup-steps` instead.
+
+## :white_check_mark: Checkpoint
+
+- [ ] You can explain why agentic workflows require ARC's Docker-in-Docker mode rather than Kubernetes mode
+- [ ] You added `runner: topology: arc-dind` to your workflow's frontmatter
+- [ ] `gh aw compile` completed without errors after the change
+- [ ] Your workflow ran successfully on your ARC runner scale set
+- [ ] You know where ARC DinD sandbox logs are written when you need to troubleshoot
+
+<!-- journey: all -->
+Return to [Run Your Agentic Workflow on a Self-Hosted Runner](24-self-hosted-runners.md).
+<!-- /journey -->