[Pedro Henrique Penna (ppenna)]

Summary

doc/design/sandbox-filesystem-and-agent-architecture.md describes the guest
init agent's filesystem assembly, but it predates the sandbox's live
virtio-fs shares. Since 13d2722 (2026-09-30), the init agent has mounted a
share inside the container root, and since c220042 (2026-10-06) a sandbox can
attach two shares, each in its own fixed virtio-fs slot with its own access
mode and host-enforced policy. None of the later edits to this chapter covered
them. The share commits updated run.md, usage.md, ci.md, and the ABI,
status, and validation chapters, but not this one. As a result, the
chapter's assembly never mounts a share, its teardown never unmounts one, and
it still calls the managed agent's mapping source "OpenVMM's single virtio-fs
export".

This PR brings the implemented-bootstrap section in line with the code. It
adds an architecture-level section on live shares that links to
run.md
for options and rules and to
machine-and-device-abi.md
for the device contract, so those facts stay stated in one place. One file
changes, all under doc/.

Changes

NVX paths are relative to the repository root. OpenVMM paths are in the pinned
submodule.

Statement	Was	Now	Evidence
What nvx sandbox accepts	Layers, scratch, entrypoint, and arguments	Adds "up to two live host shares"	MAX_MOUNTS = len(MOUNT_TAGS) with MOUNT_TAGS = ("microvm", "microvm1") (scripts/nvx_tools/sandbox.py). python scripts/nvx.py sandbox --help: "repeat to attach up to 2 shares". scripts/nvx.py accepts --mount only for run and provision.
Required kernel facilities	No virtio-fs	Adds virtio-fs	CONFIG_FUSE_FS=y and CONFIG_VIRTIO_FS=y in kernel/config-microvm. kernel/config-microvm-debug is a fragment appended to it that only enables watchdogs.
Assembly step 6	Barrier start, with the machine-ID file	Verify the identity, mount each live share at its target in the assembled root, and write the machine ID	guest/common/nvx-init-agent runs the identity checks, then mount_live_shares, then writes $runtime/workload-machine-id, and only then starts the one-shot child or the managed agent.
Assembly step 7	(was step 6)	Barrier start and cgroup placement only	Same script: nvx-container-launch behind the FIFO, with the PID written to /sys/fs/cgroup/container/cgroup.procs before start is written.
Assembly step 8 (teardown)	Unmount overlay, layers, scratch	Unmount the shares in reverse order, then the overlay, layers, and scratch	teardown() calls unmount_live_shares (most recent first) before it unmounts $rootfs, the layers, and scratch, then calls nvx-exit.
New: managed sandbox note	(not stated)	The managed agent repeats step 7 per workload, and step 8 follows stop	The init agent starts nvx-managed-agent with $rootfs, then calls teardown. With layers, the managed agent writes the child to the container cgroup, then releases the barrier, then runs nvx-container-launch (write_pid_to_cgroup, release_container_barrier, and exec_sandbox in guest/common/nvx-managed-agent.c).
Assembled view	Overlay only	Adds tags microvm and microvm1 mounted at /run/nvx/rootfs/TARGET	mount -t virtiofs -o "$share_mode,nosuid,nodev" "$share_tag" "$share_path" in the init agent. Tags from MOUNT_TAGS.
New section: Live host shares, slots	(not documented)	Each --mount gets its own fixed virtio-fs slot (microvm, microvm1) served by its own HostFs server	microvm_filesystems_from_mounts zips the mounts with MICROVM_FILESYSTEM_SLOTS (openvmm/openvmm_entry/src/microvm/filesystem.rs). openvmm/openvmm_entry/src/microvm/config.rs builds one VirtioFsBackend::HostFs per attached slot with its own policy profile.
Live host shares: host enforcement	(not documented)	The host enforces the mode and the denied, allowed, and writable paths on every request, whichever guest mount or link reaches the share, and accesses host files as the --mount-owner identity. Guest flags are not a boundary, and the policy adds no guest tokens.	The ### Filesystem section of machine-and-device-abi.md. The policy pin 3c03d93 and c0961d8 ("adds no bootstrap tokens and no guest changes"). _MOUNT_COMMAND_LINE_FRAGMENT carries only virtfs_dir, virtfs_tag, and virtfs_mode, and the policy goes to OpenVMM in mounts_openvmm_arguments. The filesystem-shares and filesystem-policy scenarios expect EROFS from OpenVMM even with the tag remounted read-write.
Live host shares: host-side rejections	(not documented)	NVX rejects a third share and policy paths outside their share before OpenVMM starts, and also overlapping guest targets or host directories	validate_mounts and validate_mount_host_paths, called from SandboxLaunch (scripts/nvx_tools/sandbox.py).
Live host shares: guest assembly	(not documented)	One triplet per share in slot order, all parsed before any mount. Each target is created one component at a time without crossing a symbolic link. The agent refuses repeated tags, overlapping targets, and targets the entry helper mounts or binds over, mounts each share MODE,nosuid,nodev, and lets the private namespace inherit it. Any refusal aborts with status 125.	mount_live_shares, mount_live_share, validate_share_target, and fatal (nvx-exit 125) in guest/common/nvx-init-agent. The entry helpers (guest/alpine/nvx-container-enter and guest/common/nvx-container-enter-azurelinux) mount /proc, /sys, /dev, and /.nvx-agent and bind /etc/machine-id. nvx-container-launch runs unshare --mount after the shares are mounted.
Live host shares: managed sandboxes	(not documented)	Shares are recorded at provisioning and reattached on every start	The mount and mounts configuration in formats 2 through 5 (scripts/nvx_tools/sandbox_lifecycle.py). Also stated in run.md.
Proposed image-delivery paragraph	"The optional HostFs device" (singular)	"The optional HostFs devices", linking to the new section	Two slots: MICROVM_FILESYSTEM_SLOTS: [MicrovmFilesystemSlot; 2] (openvmm/openvmm_defs/src/microvm.rs).
Host mappings without sandbox layers	"through OpenVMM's single virtio-fs export"	"the agent maps host directories for workloads from one virtio-fs export"	OpenVMM now has two slots. The mapping protocol still uses one export: HOSTFS_ROOT in guest/common/nvx-managed-agent.c, and aci_edge_sandboxes/src/openvmm/filesystem.rs passes a single --mount /run/nvx/hostfs/root,....

I left the rest of the section unchanged after rechecking it against the
init agent, the container helpers, and the CLI. That includes block
resolution through /proc/iomem, the sector, flush, and UUID checks, the
overlay options, the one-to-three-layer rule, the 16 MiB memory.low
default, and the managed-exec option split. scripts/nvx.py rejects
--cwd and the environment options outside sandbox exec.

OpenVMM SHA: f12dcf5e8f2ea60cc15899dd16852320530670bd, the gitlink on
dev at 33bd2fe5ef6006fb665cb5b870fa03b08e828f13. This PR does not change
the gitlink or the submodule.

Follow-ups

These are out of scope here, or blocked by open PRs or unpublished branches:

• doc/design/machine-and-device-abi.md still makes scratch mandatory
  ("Required writable final role when blocks are present"; "any nonempty
  topology ends with scratch"), which contradicts the RAM-backed overlay
  layout. The review on doc: sync cold boot with the second share and RAM overlay #442 raised this. Open PRs Support filesystem-only streamed microVM snapshots #417, Adopt bind-once microVM image slots #406, and test-microvm: pause and resume a microVM through OpenVMM state control #405 all
  modify that file, so I didn't touch it.
• doc/run.md:718 says that on stop the guest agent "unmounts the
  live share", but a sandbox can now have two. Open PR Adopt bind-once microVM image slots #406 modifies
  run.md.
• aci_edge_sandboxes/README.md:601 says "OpenVMM offers one virtio-fs
  export". So does the module comment in
  aci_edge_sandboxes/src/openvmm/filesystem.rs, which is code. The backend
  does use one export by design, but OpenVMM now offers two slots. Open PRs
  aci_edge_sandboxes: accept execution timeouts up to MXC's maximum #443 and Adopt bind-once microVM image slots #406 modify the README.
• Design coverage of the Rust sandbox library: no design chapter or
  component-map row names aci_edge_sandboxes, its OpenVMM and agent
  backends, or its model crate (git grep aci_edge -- doc/design doc/design.md
  returns nothing). doc/design/code-ownership-map.md could assign
  host-side sandbox lifecycle to it.
• doc/project-structure.md and doc/contribute.md still have the
  drift listed in doc: sync cold boot with the second share and RAM overlay #442. Local branches doc-sync/project-structure,
  doc-sync/contribute-standards, and doc-sync/contributing-guide were
  committed on 2026-10-08 but never pushed or opened as PRs. I left those
  files alone so this PR wouldn't duplicate them.
• scripts/setup/README.md is documentation outside doc/. Moving it
  means editing links in doc/ci.md and doc/setup.md, which open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405
  and Adopt bind-once microVM image slots #406 modify.
• doc/openvmm-upstream-roadmap.md still has no inbound links, and its
  fork tip 2728f33ea is 132 commits behind the pin. It needs an owner
  decision: refresh and index it, or retire it.
• Suspected stray file, not documentation: unittest_results.txt is
  still tracked.

Validation

• python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests:
  Ran 110 tests, OK (skipped=1). The skipped test needs a Linux
  pseudo-terminal, and this ran on Windows.
• I ran a throwaway checker kept outside the repo. It covered the changed
  file and every tracked Markdown file that links to it: doc/design.md,
  doc/design/cold-boot.md, doc/design/machine-and-device-abi.md,
  doc/design/snapshot-and-restore.md, doc/guests/ubuntu-guest.md, and
  doc/run.md. It confirmed that every relative link and anchor resolves,
  the changed file has one H1 and balanced code fences, and doc/design.md
  links every chapter in doc/design/. Result: 0 errors. Its self-test
  reported a planted broken link, broken anchors, a second H1, an unclosed
  fence, and an unindexed chapter, and nothing else. The new links resolve:
  #live-host-shares (used twice), machine-and-device-abi.md#filesystem,
  and ../run.md#live-host-directory-shares. The chapter's inbound anchors
  are unchanged.
• git diff --check: clean.
• python scripts/nvx.py verify: passes.
• python scripts/nvx.py classify-ci-changes --event-name pull_request on
  this diff: "Only documentation files changed", and every suite is false.
• The only changed path,
  doc/design/sandbox-filesystem-and-agent-architecture.md, matches
  ^(doc/|.*\.md$). The commit is SSH-signed.

[Copilot]

🟡 Changes recommended

The documentation incorrectly attributes single-share policy-path validation to NVX instead of OpenVMM.

1 open finding

• Clarify NVX validation scope for single-share policy paths · New

What changed in this PR

Documents live virtio-fs shares in the sandbox filesystem bootstrap architecture.

Changes:

• Adds share mounting, teardown, security, and lifecycle details.
• Updates HostFs terminology for multiple filesystem slots.

File	Description
doc/​design/​sandbox-filesystem-and-agent-architecture.md	Documents live-share bootstrap and managed-sandbox behavior.

🧠 Review effort: Balanced

---

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