[Pedro Henrique Penna (ppenna)]

Summary

The design docs start from the component responsibility map, but neither it nor the sandbox filesystem and agent architecture chapter named the aci_edge_sandboxes crate, which is a second host component that launches NVX microVMs. The chapter already describes the blockless managed path that the crate uses (under Control protocol and checkpoint handoff), but it doesn't say which host component drives it. This PR names the crate, its two backends, the guest path that serves blockless workloads, and the crate's tests. It adds no new contract detail and links to the crate README for the API.

Changes

Statement	Evidence
The nvx sandbox command attaches image layers and scratch, which the guest assembles into the layered root. The existing map row is renamed to Layered sandbox launch.	scripts/nvx_tools/sandbox.py passes --microvm-sandbox-block. guest/common/init runs nvx-init-agent only with nvx_sandbox=1.
aci_edge_sandboxes exposes provision, start, exec, stop, and deprovision, and its contract model lives in a data-model crate.	aci_edge_sandboxes/src/lib.rs, aci_edge_sandboxes/Cargo.toml (aci_edge_sandboxes_model path dependency), aci_edge_sandboxes/model/src/lib.rs
The default backend launches OpenVMM directly with the managed lifecycle and no sandbox blocks, so workloads run in the Alpine initramfs root.	aci_edge_sandboxes/src/openvmm/launch.rs (--microvm-lifecycle managed, no --microvm-sandbox-block, no nvx_sandbox=1; the unit test asserts the block flag is absent). guest/common/init then starts nvx-managed-agent with no container root.
The default backend keeps durable sandbox records, reconciles the OpenVMM process, exports host paths, and translates egress rules.	Module docs and reconcile in aci_edge_sandboxes/src/openvmm/mod.rs, plus filesystem.rs and network.rs
The guest init and managed agent own blockless workloads, host-path binds (nvx_map=), and workload account creation (nvx_workload_account=create).	guest/common/init (ensure_workload_account), guest/common/nvx-managed-agent.c (MAP_TOKEN)
The optional agent backend delegates to a separately supplied native library and an image-backed edge guest that NVX does not build.	aci_edge_sandboxes/src/agent/, the agent feature in Cargo.toml. No build script under scripts/, docker/, or guest/ produces an edge initramfs.
The crate's tests cover the contract, a fake OpenVMM, and real-hypervisor lifecycles.	aci_edge_sandboxes/tests/{validation,mock_backend,openvmm_fake,openvmm_e2e}.rs, scripts/nvx.py test-aci-edge-sandboxes

Pinned OpenVMM: f12dcf5e8f2ea60cc15899dd16852320530670bd (unchanged). The design text relies on it only for the managed-lifecycle and sandbox-block options. The nvx_sandbox=1 token is a caller token that OpenVMM does not add.

Conservative choices:

• I didn't claim in the design docs that the agent backend's edge guest uses the nvx_overlay_upper=ramfs layout. Only the crate README and the pin commit message say so, and that guest isn't built from this repository.
• I didn't touch any file that an open PR changes (network: support MXC-shaped rule-local CIDR exclusions #447, Support filesystem-only streamed microVM snapshots #417, Adopt bind-once microVM image slots #406, test-microvm: pause and resume a microVM through OpenVMM state control #405).

Follow-ups (out of scope)

• THIRD_PARTY_NOTICES.md still calls OpenVMM a private submodule that only authorized users can access. nanvix/openvmm is public (gh api repos/nanvix/openvmm reports "private": false). The same stale wording is in doc/ci.md (the OPENVMM_DEPLOY_KEY paragraph) and doc/run.md (the download token note). An open PR touches each of these, or the file is outside this run's edit boundary.
• doc/openvmm-upstream-roadmap.md is a point-in-time plan that pins fork tip 2728f33ea, but the current pin is f12dcf5e8. It needs either a refresh or an explicit dated-snapshot label.
• scripts/setup/README.md is documentation outside doc/. Moving it would also require updating a path check in scripts/test_nvx_tools.py, so it needs a code-and-doc change.
• doc/design/validation.md doesn't list the aci_edge_sandboxes real-hypervisor lifecycle suite among the validation layers.
• unittest_results.txt is a tracked file at the repository root that looks like a stray test log.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests: 110 tests passed (1 skipped).
• I ran a throwaway link checker outside the repository on both changed files and on every file that links to them: doc/design.md, cold-boot.md, machine-and-device-abi.md, snapshot-and-restore.md, doc/guests/ubuntu-guest.md, and doc/run.md. All relative links and anchors resolve, each changed file has one H1 and balanced code fences, and doc/design.md links every chapter in doc/design/.
• git diff --check: clean.
• python scripts/nvx.py verify: passed.

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the implementation and introduces no unresolved issues.

0 open findings

What changed in this PR

Documents aci_edge_sandboxes within NVX’s sandbox architecture and component ownership map.

Changes:

• Describes both sandbox launch paths and their guest models.
• Maps crate backends, guest responsibilities, and lifecycle tests to their owning components.

File	Description
doc/​design/​sandbox-filesystem-and-agent-architecture.md	Names the crate, backends, lifecycle API, and blockless workload path.
doc/​design/​code-ownership-map.md	Adds ownership entries for edge sandbox runtime components and tests.

🧠 Review effort: Balanced

---

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