docs: document .awf-home prerequisite for Cloud Hypervisor allowWrite - #7670
Conversation
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
There was a problem hiding this comment.
Pull request overview
Documents the host .awf-home prerequisite for writable Cloud Hypervisor guest homes.
Changes:
- Explains why
.awf-homemust exist before planning. - Adds setup and
allowWriteexamples. - Clarifies narrowing semantics.
Show a summary per file
| File | Description |
|---|---|
docs/cloud-hypervisor-foundation.md |
Adds prerequisite details and examples. |
docs/awf-config-spec.md |
Defines the prerequisite normatively. |
Review details
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Files reviewed: 2/2 changed files
- Comments generated: 4
- Review effort level: Balanced
| the host directory before AWF starts, then list the guest path: | ||
|
|
||
| ```bash | ||
| mkdir -p "$GITHUB_WORKSPACE/.awf-home" |
| 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 |
| 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 |
|
⏳ Copilot review left inline comments. @lpcox To proceed:
|
|
📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤
|
|
❌ Smoke Copilot BYOK AOAI (Entra) reports failed. AOAI BYOK (Entra) mode investigation needed...
|
|
✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟 Warning Firewall blocked 3 domainsThe following domains were blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "msfeed2.pkgs.visualstudio.com"
- "msfeed25.pkgs.visualstudio.com"
- "registry.npmjs.org"See Network Configuration for more information.
|
|
✅ Build Test Suite completed successfully!
|
|
🔌 Smoke Services — All services reachable! ✅
|
|
📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅
|
|
📰 VERDICT: Smoke Docker Sbx has concluded. All systems operational. This is a developing story. 🎤
|
|
🛡️ Smoke Copilot Network Isolation confirmed the egress allowlist is enforced. ✅ Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "example.com"See Network Configuration for more information.
|
|
🚀 Security Guard has started processing this pull request |
|
✅ Smoke Copilot BYOK AOAI (api-key) completed. Copilot AOAI BYOK (api-key) mode operational. 🔓
|
|
✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓
|
|
❌ Smoke Gemini reports failed. Facets need polishing...
|
|
✅ Smoke Claude passed
|
|
Chroot tests passed! Smoke Chroot - All security and functionality tests succeeded.
|
|
✅ Contribution Check completed successfully! Contribution check complete — no guideline issues found in PR #7670; docs-only change includes updated documentation in the touched docs files and the PR description clearly references the related PR (#7669).
|
This comment has been minimized.
This comment has been minimized.
github-actions
Bot
added
the
smoke-copilot-network-isolation
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
✅ Smoke Copilot BYOK AOAI (api-key) completed. Copilot AOAI BYOK (api-key) mode operational. 🔓
|
|
✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟 Warning Firewall blocked 3 domainsThe following domains were blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "msfeed2.pkgs.visualstudio.com"
- "msfeed25.pkgs.visualstudio.com"
- "registry.npmjs.org"See Network Configuration for more information.
|
|
📰 VERDICT: Smoke Docker Sbx has concluded. All systems operational. This is a developing story. 🎤
|
|
❌ Smoke Gemini reports failed. Facets need polishing...
|
|
🚀 Security Guard has started processing this pull request |
|
✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓
|
|
✅ Smoke Copilot BYOK AOAI (Entra) completed. Copilot AOAI BYOK (Entra) mode operational. 🔓
|
|
📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅
|
|
🔌 Smoke Services — All services reachable! ✅
|
|
Smoke Test: Copilot Engine — @lpcox
PR #7670: docs: document .awf-home prerequisite for Cloud Hypervisor allowWrite Overall: PASS
|
|
@lpcox Network isolation egress smoke test results: EGRESS_RESULT allow=pass deny=pass
Overall: PASS Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "example.com"See Network Configuration for more information.
|
Smoke Test: Claude Engine Validation
Overall result: PASS
|
Smoke Test: Copilot BYOK (Direct) Mode ✅
Status: PASS — Direct BYOK mode (COPILOT_PROVIDER_API_KEY) working correctly.
|
|
Smoke Test: Docker Sbx — @lpcox
Overall: PASS
|
Chroot Version Comparison Results
Overall: FAILED — Node.js version mismatch between host and chroot environment.
|
|
GitHub MCP Testing: ✅ Running in direct BYOK mode (COPILOT_PROVIDER_API_KEY + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw)
|
|
Smoke Test: Services Connectivity — FAIL
|
Warning Firewall blocked 3 domainsThe following domains were blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "msfeed2.pkgs.visualstudio.com"
- "msfeed25.pkgs.visualstudio.com"
- "registry.npmjs.org"See Network Configuration for more information.
|
|
fix: make Cloud Hypervisor writable overlays privately propagated: ✅
|
|
Smoke Test: API Proxy OTEL Tracing — results
All scenarios pass or behave as expected. No issues found.
|
🏗️ Build Test Suite Results
Overall: 8/8 ecosystems passed — PASS Notes
|
Documentation-only follow-up to #7669 (merged as
664ffc1c), fixing a docs correctness issue found in final review.Problem
Both docs told readers that if a narrowing
filesystem.allowWritepolicy makes the guest home read-only, the remedy is to "add the home path toallowWrite". That remedy fails as written.The Cloud Hypervisor workspace export is backed by the host workspace directory itself (
src/cloud-hypervisor/exports.tsresolvesenvironment.GITHUB_WORKSPACE || cwd), and nothing in the Cloud Hypervisor path creates.awf-homeon the host before planning. Notesrc/microvm/workspace.tsdoes create it during staging, but that module is not used by the Cloud Hypervisor backend — CH imports onlyguest-environment,infrastructure,vsock-client,network, androotfsfromsrc/microvm/.So:
resolveWritableOverlay()→fs.realpathSync→catch { return undefined }), naming it inallowWritethrows instead.Empirically confirmed against the real planner:
With the host directory pre-created, the same input plans correctly:
{"disposition":"selective","hostRootMode":"ro","guestMountMode":"rw", "overlays":[{"guest":"/workspace/.awf-home","kind":"directory"}]}Change
Document the missing prerequisite in
docs/cloud-hypervisor-foundation.mdanddocs/awf-config-spec.md: create the host directory$GITHUB_WORKSPACE/.awf-homebefore AWF starts, then list the guest path/workspace/.awf-home. Includes a short setup example and the resulting plan shape.Both docs now state plainly that AWF deliberately does not auto-create or exempt the guest home, since either would widen the boundary implicitly or reintroduce an always-writable internal mount — contradicting the narrowing semantics.
Scope
docs/awf-config.schema.jsonneeded no change — itsallowWritedescription already says "Paths must exist".*.md).Validation
npm run lint:md— 159 files, 0 issuesplanCloudHypervisorFilesystemWrites, since removed.