Complete Cloud Hypervisor runtime compilation

[lpcox]

Summary

Completes the Cloud Hypervisor (preview) microVM runtime for AWF-sandboxed agents. Adds a virtiofsd binary to the release bundle and its checksum/manifest verification, grants the runner scoped /dev/kvm access via a dedicated setup step, switches the AWF invocation to a privileged sudo --preserve-env awf command instead of legacy -E sudo, sizes the guest VM (2 vCPUs, 4096 MiB), attaches the MCP gateway to the isolated network topology (while explicitly excluding the CLI proxy sidecar), and adds compile-time validation that rejects unsupported feature combinations (gh-proxy mode, legacy-security, allow-host-ports, enclaves) when sandbox.agent.runtime: cloud-hypervisor is set.

Change Classification

• Type: feature
• Scope: pkg/workflow (AWF command builder, config, install, validation), pkg/constants, actions/setup/sh, pkg/parser/schemas, docs
• Breaking: No — cloud-hypervisor is preview-only; other runtimes (gvisor, docker-sbx) are unaffected. Existing cloud-hypervisor workflows using now-rejected combinations (gh-proxy, legacy-security, allow-host-ports, enclaves) will fail validation at compile time going forward.

Key Changes

File	Change	Impact
actions/setup/sh/cloud_hypervisor_kvm_access.sh	New script granting the runner user scoped read/write ACL on /dev/kvm, restricted to GitHub-hosted Ubuntu x86_64	Enables non-root KVM access without loosening host device permissions
actions/setup/sh/cloud_hypervisor_setup_bundle.sh	Adds virtiofsd path/sha256 resolution, colocation check, and manifest schema/digest cross-validation	Ensures virtiofsd is downloaded, verified, and made executable alongside the hypervisor binary
pkg/workflow/awf_command_builder.go	Adds --cloud-hypervisor-vcpus/--cloud-hypervisor-memory-mib args, --cloud-hypervisor-virtiofsd-sha256, and switches command prefix to sudo --preserve-env awf for this runtime	Cloud Hypervisor now runs with defined guest sizing and correct privileged invocation
pkg/workflow/awf_config.go	Always builds the topology attach list (previously skipped for cloud-hypervisor); CLI proxy still excluded per-runtime	MCP gateway is now reachable from the cloud-hypervisor guest
pkg/workflow/cloud_hypervisor_install.go	Adds generateCloudHypervisorKVMAccessStep	Wires the new KVM ACL step into engine installation flows
pkg/workflow/codex_engine.go, pkg/workflow/nodejs.go	Insert the KVM access step before host preflight/bundle setup	Ensures KVM permissions are set before the runtime is used
pkg/workflow/copilot_engine_installation.go, pkg/workflow/engine_firewall_support.go	Treat cloud-hypervisor like legacy-security for --rootless/install-path decisions	Keeps AWF binary path and firewall log parsing consistent with the privileged invocation
pkg/workflow/sandbox_validation.go	Adds compile-time rejection of gh-proxy, legacy-security, allow-host-ports, and enclaves with cloud-hypervisor	Surfaces incompatible configurations as validation errors instead of silent runtime failures
pkg/constants/constants.go	Adds AWFCloudHypervisorCommand, DefaultCloudHypervisorVCPUs, DefaultCloudHypervisorMemoryMiB	Centralizes new runtime defaults
pkg/parser/schemas/main_workflow_schema.json, docs/public/editor/autocomplete-data.json, docs/src/content/docs/reference/*, docs/src/content/docs/introduction/architecture.mdx	Updated schema description and reference docs for the completed runtime behavior; unrelated schema additions (ambient-folders, enclaves, Vertex AI WIF fields, cache/repo-memory validation hooks, OTLP workload-identity)	Documents actual compiler behavior; schema additions reflect other concurrently-documented features
pkg/workflow/cloud_hypervisor_test.go	New/updated tests for KVM step ordering, vcpu/memory args, privileged command, topology attach, and each new validation rejection	Verifies the new behavior end-to-end via lock-file generation

Impact Assessment

• Workflows using sandbox.agent.runtime: cloud-hypervisor now install a KVM ACL step, download virtiofsd, and invoke AWF with sudo --preserve-env and explicit vCPU/memory flags — regenerated lock files for such workflows will change.
• Workflows combining cloud-hypervisor with tools.github.mode: gh-proxy, sandbox.agent.legacy-security: enable, sandbox.agent.allow-host-ports, or enclaves will now fail gh aw compile with a descriptive validation error.
• MCP gateway (awmg-mcpg) is now attached to the isolated network topology for cloud-hypervisor guests; the CLI proxy sidecar remains unattached.
• JSON schema and autocomplete data updates affect editor tooling and gh aw compile schema validation for several unrelated new frontmatter fields introduced alongside this change.

Commits

2d7eab7ec Reject unsupported cloud-hypervisor combinations at compile time
038b38e18 Complete Cloud Hypervisor runtime compilation
```> Generated by [PR Description Updater](https://github.com/github/gh-aw/actions/runs/31757932886) for #52588 · auto · 54.2 AIC · ⌖ 5.62 AIC · ⊞ 7.2K · [◷](https://github.com/search?q=repo%3Agithub%2Fgh-aw+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw%2Fpr-description-caveman%22&type=pullrequests)

<!-- gh-aw-agentic-workflow: PR Description Updater, engine: copilot, model: auto, id: 31757932886, workflow_id: pr-description-caveman, run: https://github.com/github/gh-aw/actions/runs/31757932886 -->

[Copilot]

Pull request overview

Completes compiler support for AWF’s Cloud Hypervisor runtime and its companion firewall release.

Changes:

• Adds scoped KVM access and verified runtime-bundle provisioning.
• Emits privileged AWF invocation, runtime sizing, timeout, and topology configuration.
• Updates tests, schema, and runtime documentation.

Show a summary per file

File	Description
pkg/workflow/nodejs.go	Adds KVM setup for Node.js engines.
pkg/workflow/engine_firewall_support.go	Uses privileged firewall-log parsing.
pkg/workflow/copilot_engine_installation.go	Installs AWF system-wide for Cloud Hypervisor.
pkg/workflow/codex_engine.go	Adds KVM setup for Codex.
pkg/workflow/cloud_hypervisor_test.go	Expands runtime compilation tests.
pkg/workflow/cloud_hypervisor_install.go	Generates the KVM access step.
pkg/workflow/awf_config.go	Adds timeout and topology configuration.
pkg/workflow/awf_command_builder.go	Adds privileged invocation and runtime flags.
pkg/parser/schemas/main_workflow_schema.json	Documents runtime behavior in the schema.
pkg/constants/constants.go	Defines command and sizing defaults.
docs/src/content/docs/reference/glossary.md	Updates the runtime glossary.
docs/src/content/docs/reference/frontmatter-full.md	Refreshes generated frontmatter documentation.
docs/src/content/docs/reference/agent-runtimes.md	Documents runtime setup and isolation.
docs/src/content/docs/introduction/architecture.mdx	Updates the architecture matrix.
docs/public/editor/autocomplete-data.json	Refreshes editor metadata.
actions/setup/sh/cloud_hypervisor_setup_bundle.sh	Verifies and exports the runtime bundle.
actions/setup/sh/cloud_hypervisor_kvm_access.sh	Grants runner-scoped KVM access.

Review details

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 17/17 changed files
• Comments generated: 3
• Review effort level: Balanced

[gh-aw-bot]

@copilot Please review the latest Cloud Hypervisor runtime branch state, refresh the branch if needed, and run the pr-finisher skill before handing this PR back to maintainers.

Outstanding review items (newest first):

• No unresolved blocker was obvious from the compact context; please verify there are no remaining review-thread follow-ups or checks needing action.

Failed checks from the compact candidate set:

• None listed.

Branch update could not be requested automatically in this run because the local gh aw checks helper was unavailable.
Run: https://github.com/github/gh-aw/actions/runs/31746457772

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 10.9 AIC · ⌖ 7.21 AIC · ⊞ 8.5K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot Please review the latest Cloud Hypervisor runtime branch state, refresh the branch if needed, and run the pr-finisher skill before handing this PR back to maintainers.

Outstanding review i...

Added compile-time validation rejecting sandbox.agent.runtime: cloud-hypervisor combined with gh-proxy/integrity-reactions, legacy-security/allow-host-ports, and enclaves, with tests and doc updates (038b38e follow-up commit). All three copilot-pull-request-reviewer threads on this PR are addressed by that change.

[gh-aw-bot]

@copilot Please resolve the remaining unresolved review threads, refresh the branch if needed, and run the pr-finisher skill before handing this PR back to maintainers.

Outstanding review items (newest first):

• copilot-pull-request-reviewer: Complete Cloud Hypervisor runtime compilation #52588 (comment)
• copilot-pull-request-reviewer: Complete Cloud Hypervisor runtime compilation #52588 (comment)
• copilot-pull-request-reviewer: Complete Cloud Hypervisor runtime compilation #52588 (comment)

Failed checks from the compact candidate set:

• None listed.

Branch update was requested automatically for this run.
Run: https://github.com/github/gh-aw/actions/runs/31749685094

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 13.8 AIC · ⌖ 8.11 AIC · ⊞ 8.5K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot Please resolve the remaining unresolved review threads, refresh the branch if needed, and run the pr-finisher skill before handing this PR back to maintainers.

Outstanding review items (ne...

All three referenced threads (r3779408217, r3779408210, r3779408192) are my own replies on the already-resolved threads from commit 2d7eab7 — they're marked resolved in the PR's review state, not new unresolved feedback. Local build and the focused Cloud Hypervisor tests pass on the current HEAD; no further changes needed.

[gh-aw-bot]

Caution

agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation.

Details

Potential security threats were detected in the agent output.

Review the workflow run logs for details.

@copilot Please resolve the remaining unresolved review threads, refresh the branch if needed, and run the pr-finisher skill before handing this PR back to maintainers.

Outstanding review items (newest first):

• copilot-pull-request-reviewer: Complete Cloud Hypervisor runtime compilation #52588 (comment)
• copilot-pull-request-reviewer: Complete Cloud Hypervisor runtime compilation #52588 (comment)
• copilot-pull-request-reviewer: Complete Cloud Hypervisor runtime compilation #52588 (comment)

Failed checks from the compact candidate set:

• None listed.

Branch update could not be requested automatically in this run because the safe update path was unavailable in the current environment.
Run: https://github.com/github/gh-aw/actions/runs/31752692121

Generated by 👨🍳 PR Sous Chef
_{Comment /souschef to run again}

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 7.25 AIC · ⌖ 6.28 AIC · ⊞ 8.5K · ◷
_{Comment /souschef to run again}

[Copilot]

[!CAUTION]
agentic threat detected
Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation....

The three listed threads (r3779408217, r3779408210, r3779408192) are already resolved by commit 2d7eab7, which added the compile-time validations in validateSandboxConfig for gh-proxy/integrity-reactions, legacy-security/allow-host-ports, and enclaves with cloud-hypervisor. Verified again on current HEAD — build is clean and no further changes are needed.

[gh-aw-bot]

@copilot Please verify the already-addressed review replies are reflected in the current PR thread state, refresh the branch if needed, and run the pr-finisher skill before handing this PR back to maintainers.

Outstanding review items (newest first):

• copilot-pull-request-reviewer: please reconcile the remaining thread state with your latest author replies that say the three cited items are already resolved on the current head.

Failed checks from the compact candidate set:

• None listed.

Branch update was not requested automatically in this run because the PR already has recent completed follow-up activity.
Run: https://github.com/github/gh-aw/actions/runs/31755466716

Generated by 👨‍🍳 PR Sous Chef · gpt54 · 15.5 AIC · ⌖ 6.8 AIC · ⊞ 8.5K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot Please verify the already-addressed review replies are reflected in the current PR thread state, refresh the branch if needed, and run the pr-finisher skill before handing this PR back to m...

Confirmed via the GitHub API: all three threads (r3779408192, r3779408210, r3779408217) show is_resolved: true in the current PR state. Thread state and my replies are correctly reconciled — no further action needed.