github · lpcox · Jul 4, 2026 · Jul 3, 2026 · Jul 3, 2026 · Jul 4, 2026
diff --git a/docs/arc-dind.md b/docs/arc-dind.md
@@ -160,6 +160,7 @@ filesystem. Prefer a shared runner/daemon path under `/tmp/gh-aw` when possible.
 AWF detects likely ARC/DinD environments at startup and warns when `--docker-host-path-prefix` is missing:
 
 - non-default unix `DOCKER_HOST` socket paths (outside `/var/run/docker.sock` and `/run/docker.sock`)
+- loopback TCP `DOCKER_HOST` endpoints (`tcp://localhost:*` or `tcp://127.0.0.1:*`) — the standard ARC RunnerScaleSet DinD sidecar configuration
 - `AWF_DIND=1`
 
 ## Recommended DinD base image
@@ -173,3 +174,9 @@ It includes `docker-ce`, `libcap2-bin` (`capsh`), and Node.js preinstalled.
 ## Runtime prerequisite
 
 Copilot CLI still requires `node` to be available inside the chrooted runtime PATH.
+
+## See also
+
+- [docs/awf-config-spec.md](awf-config-spec.md) — Normative field reference and CLI mapping for all ARC/DinD config fields (`container.dockerHostPathPrefix`, `container.enableDind`, `container.dockerHost`, `chroot.*`, `dind.*`, `runner.*`)
+- [docs/awf-config.schema.json](awf-config.schema.json) — Machine-readable JSON Schema for IDE validation
+- [docs/environment.md](environment.md) — `DOCKER_HOST` handling, `AWF_DIND`, and split-filesystem guidance
diff --git a/docs/awf-config-spec.md b/docs/awf-config-spec.md
@@ -1553,6 +1553,8 @@ https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/cli-proxy-a
 
 ## Informative References
 
+- [docs/arc-dind.md](arc-dind.md) — ARC/DinD split-filesystem architecture, sysroot
+  staging, and end-to-end configuration examples
 - [docs/environment.md](environment.md) — Usage guide for environment
   variables
 - [docs/authentication-architecture.md](authentication-architecture.md) —

diff --git a/docs/awf-config.schema.json b/docs/awf-config.schema.json
@@ -562,7 +562,7 @@
         },
         "enableDind": {
           "type": "boolean",
-          "description": "Enable Docker-in-Docker support inside the agent container."
+          "description": "Expose the Docker socket inside the agent container so the agent can run docker commands. When combined with container.dockerHost (or the DOCKER_HOST environment variable), AWF uses that socket path for both AWF's own operations and the in-agent DOCKER_HOST. WARNING: allows the agent to bypass the AWF firewall via docker run."
         },
         "workDir": {
           "type": "string",
@@ -598,7 +598,7 @@
         },
         "dockerHost": {
           "type": "string",
-          "description": "Docker daemon socket or host to connect to (e.g. \"unix:///var/run/docker.sock\")."
+          "description": "Docker daemon socket URI for AWF's own operations (e.g. \"unix:///var/run/docker.sock\" or \"tcp://localhost:2375\"). Auto-detected from the DOCKER_HOST environment variable when not set explicitly. When combined with container.enableDind, AWF also mounts that socket inside the agent and sets the agent's DOCKER_HOST to the same URI so in-agent docker commands use the correct daemon. On ARC/DinD runners with a loopback TCP daemon (tcp://localhost:* or tcp://127.0.0.1:*), AWF treats this as a DinD hint for warnings (for example, missing container.dockerHostPathPrefix), but does not auto-apply a path prefix."
         },
         "dockerHostPathPrefix": {
           "type": "string",
@@ -797,7 +797,7 @@
             "standard",
             "arc-dind"
           ],
-          "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF applies overridable defaults: network.isolation=true, dind.preStageDirs=true, sysroot image activation, and tool cache validation."
+          "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF enables sysroot staging (a sysroot-stage init container copies the build-tools image into a named volume mounted at /host:rw on the agent) and emits a warning when RUNNER_TOOL_CACHE points under /opt (which is typically invisible to the DinD daemon). Other ARC/DinD settings such as container.dockerHostPathPrefix, dind.preStageDirs, and network.isolation are configured explicitly through their own fields. See docs/arc-dind.md for a complete guide."
         },
         "sysrootImage": {
           "type": "string",

diff --git a/docs/environment.md b/docs/environment.md
@@ -365,6 +365,8 @@ container:
 | ARC runner with DinD sidecar | Yes — set to the host mount prefix (e.g. `/host`) |
 | ARC runner with Docker socket mount | Only if the runner and daemon have different filesystem views |
 
+> **See also:** [docs/arc-dind.md](arc-dind.md) for a complete ARC/DinD configuration guide, including sysroot staging, tool-cache guidance, and end-to-end examples.
+
 ### Security: procfs and credential isolation
 
 AWF mounts a container-scoped procfs at `/host/proc` with `hidepid=2` to prevent the agent from reading other processes' environment variables. This is critical because:

diff --git a/docs/usage.md b/docs/usage.md
@@ -888,6 +888,11 @@ sudo awf --enable-dind --allow-domains registry-1.docker.io -- docker run hello-
 > restrictions by spawning containers that are not subject to the firewall's network
 > rules.  Only enable it for trusted workloads that genuinely need Docker access.
 
+> **ARC/DinD (split runner/daemon filesystem):** If you are running AWF on an ARC
+> runner where the runner pod and the Docker daemon have separate filesystems, see
+> [docs/arc-dind.md](arc-dind.md) for the correct configuration using
+> `--docker-host-path-prefix`, `runner.topology: arc-dind`, and sysroot staging.
+
 ## IP-Based Access
 
 Direct IP access (without domain names) is blocked:

diff --git a/src/awf-config-schema.json b/src/awf-config-schema.json
@@ -562,7 +562,7 @@
         },
         "enableDind": {
           "type": "boolean",
-          "description": "Enable Docker-in-Docker support inside the agent container."
+          "description": "Expose the Docker socket inside the agent container so the agent can run docker commands. When combined with container.dockerHost (or the DOCKER_HOST environment variable), AWF uses that socket path for both AWF's own operations and the in-agent DOCKER_HOST. WARNING: allows the agent to bypass the AWF firewall via docker run."
         },
         "workDir": {
           "type": "string",
@@ -598,7 +598,7 @@
         },
         "dockerHost": {
           "type": "string",
-          "description": "Docker daemon socket or host to connect to (e.g. \"unix:///var/run/docker.sock\")."
+          "description": "Docker daemon socket URI for AWF's own operations (e.g. \"unix:///var/run/docker.sock\" or \"tcp://localhost:2375\"). Auto-detected from the DOCKER_HOST environment variable when not set explicitly. When combined with container.enableDind, AWF also mounts that socket inside the agent and sets the agent's DOCKER_HOST to the same URI so in-agent docker commands use the correct daemon. On ARC/DinD runners with a loopback TCP daemon (tcp://localhost:* or tcp://127.0.0.1:*), AWF treats this as a DinD hint for warnings (for example, missing container.dockerHostPathPrefix), but does not auto-apply a path prefix."
         },
         "dockerHostPathPrefix": {
           "type": "string",
@@ -797,7 +797,7 @@
             "standard",
             "arc-dind"
           ],
-          "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF applies overridable defaults: network.isolation=true, dind.preStageDirs=true, sysroot image activation, and tool cache validation."
+          "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF enables sysroot staging (a sysroot-stage init container copies the build-tools image into a named volume mounted at /host:rw on the agent) and emits a warning when RUNNER_TOOL_CACHE points under /opt (which is typically invisible to the DinD daemon). Other ARC/DinD settings such as container.dockerHostPathPrefix, dind.preStageDirs, and network.isolation are configured explicitly through their own fields. See docs/arc-dind.md for a complete guide."
         },
         "sysrootImage": {
           "type": "string",