From 4a94b3345e712faa28e7600a902cc73a675efe19 Mon Sep 17 00:00:00 2001 From: Landon Cox Date: Sun, 23 Aug 2026 11:42:14 -0700 Subject: [PATCH] docs: document .awf-home prerequisite for Cloud Hypervisor allowWrite The allowWrite guidance told readers to add `/workspace/.awf-home` to `filesystem.allowWrite` when a narrowed policy makes the guest home read-only, but that remedy fails as written. The Cloud Hypervisor workspace export is backed by the host workspace directory itself, and nothing in the Cloud Hypervisor path creates `.awf-home` on the host before planning. Without a policy this is invisible: the export is writable and the directory is created at runtime. Under a narrowing policy the export root is staged read-only, so runtime creation is no longer possible, and because the planner only accepts paths that already exist, naming it in `allowWrite` throws: filesystem.allowWrite path is not an existing path within a writable Cloud Hypervisor export: /workspace/.awf-home Document the missing prerequisite in both the Cloud Hypervisor foundation doc and the config spec: create the host directory `$GITHUB_WORKSPACE/.awf-home` before AWF starts, then list the guest path. Include a short setup example and state plainly that AWF does not auto-create or exempt the guest home, since either would widen the boundary implicitly or reintroduce an always-writable internal mount. Documentation only; no behaviour, existing-path, or narrowing semantics change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 248b577f-2e6f-4e03-90bc-96c75c0d395e --- docs/awf-config-spec.md | 10 +++++++-- docs/cloud-hypervisor-foundation.md | 33 +++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/awf-config-spec.md b/docs/awf-config-spec.md index 552fba34f..967431126 100644 --- a/docs/awf-config-spec.md +++ b/docs/awf-config-spec.md @@ -106,8 +106,14 @@ where it is enforced by the host mount tree that backs each virtio-fs export Cloud Hypervisor has no always-writable internal mounts, so every export it publishes is subject to the policy, including `/tmp/gh-aw` and the guest home directory at `/workspace/.awf-home`; paths not covered by `allowWrite` become -read-only. AWF rejects `filesystem.allowWrite` with the sbx -runtime and with Docker-in-Docker agent execution. +read-only. Because every listed path MUST already exist, and because AWF MUST +NOT auto-create or exempt the guest home, a Cloud Hypervisor workload that needs +a writable home MUST have the backing host directory +`$GITHUB_WORKSPACE/.awf-home` created before AWF starts and MUST then list the +guest path `/workspace/.awf-home` in `allowWrite`; otherwise planning fails +because the path does not exist within a writable export. AWF rejects +`filesystem.allowWrite` with the sbx runtime and with Docker-in-Docker agent +execution. ### 4.2 Cloud Hypervisor microVM preview diff --git a/docs/cloud-hypervisor-foundation.md b/docs/cloud-hypervisor-foundation.md index c63daf152..c797003ec 100644 --- a/docs/cloud-hypervisor-foundation.md +++ b/docs/cloud-hypervisor-foundation.md @@ -357,6 +357,39 @@ One consequence is worth stating plainly: the guest `HOME` is directory read-only. That is the policy working as specified, not an oversight; add the home path to `allowWrite` if the workload needs it. +Doing so has a prerequisite. The workspace export is backed by the host +workspace directory itself (`$GITHUB_WORKSPACE`, falling back to the current +working directory), and nothing in the Cloud Hypervisor path creates +`.awf-home` on the host before planning. That is harmless without a policy, +because the export is writable and the directory is simply created at runtime. +Under a narrowing policy the export root is staged read-only, so it can no +longer be created at runtime — and the planner only accepts paths that already +exist, so naming it in `allowWrite` fails too, with a single-line error: + +```text +filesystem.allowWrite path is not an existing path within a writable +Cloud Hypervisor export: /workspace/.awf-home +``` + +AWF deliberately does not auto-create or exempt the guest home: doing either +would either widen the boundary implicitly or reintroduce an always-writable +internal mount, both of which contradict the narrowing semantics above. Create +the host directory before AWF starts, then list the guest path: + +```bash +mkdir -p "$GITHUB_WORKSPACE/.awf-home" +``` + +```yaml +filesystem: + allowWrite: + - /workspace/.awf-home +``` + +That yields a `selective` workspace plan — host root staged `ro`, guest mount +`rw`, one directory overlay at `.awf-home` — leaving the rest of the workspace +read-only. + ## Limitations The preview rejects configurations that weaken or conflict with its boundary,