Repository navigation
Closed
Description
Goal. Adapters that embed nvx-rs through its public APIs keep their own copies of three things that NVX already implements, because NVX keeps them private or offers them only to its managed launches. Expose them, so that every adapter shares NVX's implementation and its tests.
Today (dev ce8c7d67):
-
The guest's host mapping table.
- The managed agent keeps the table's state in
HostMappings: the count that the kernel command line announces, the mappings applied so far, whether a failure refused the rest, and the table's mapper and export (nvx-rs/src/guest/managed_agent/mappings.rs:25). preparereads the announcement and checks the export's mount (:113).apply_requestchecks eachMAPSpart against the table, applies its mappings in order beneath the table's root, and latches the table at the first entry that fails (:148).teardownunmounts the mappings in reverse order and reports each failure with its entry (:240).- All of it is crate-private, in a private module (
nvx-rs/src/guest/managed_agent/mod.rs:93). An adapter's guest hasnvx::guest::root::Root::map,nvx::guest::mappingsandnvx::protocol::decode_guest_maps_payload, and keeps the table's state itself, as the test adapter's worker does (tests/runtime-adapter/src/worker.rs:33-84).
- The managed agent keeps the table's state in
-
The rest of an adapter's launch arguments.
LaunchSpec::openvmm_argumentsrenders OpenVMM's whole command line for a managed launch (nvx-rs/src/host/launch.rs:234).- For an adapter's launch,
PreparedLaunchrenders only the plan's options and the kernel command line (nvx-rs/src/host/sandbox/prepared.rs:281,:288). Each adapter adds the rest itself:--single-process,--hypervisor,--memory,--kernel,--initrd,--cmdline,--virtio-console,--microvm-control-console,--microvm-control-auth-stdinand--microvm-report, as the test adapter does (tests/runtime-adapter/src/layered.rs:284-330). A change to OpenVMM's options has to reach every copy.
-
The process command-line count.
process_command_line_unitscounts the Windows command line that runs a program with its arguments, as Windows quotes it (nvx-rs/src/host/launch.rs:372), and is private.fit_process_command_lineis crate-private (:284), and so is its reserve (:28).LaunchSpec::check_process_command_line(:277) checks a managed launch only.- Nothing checks an adapter's launch against
PROCESS_COMMAND_LINE_LIMIT(:25), so a plan with many mapped paths or network rules can render a command line that Windows refuses when it creates the VMM. An adapter that checks it counts again, with its own copy of the quoting rules.
Proposal:
- A public guest-side type for the host mapping table, with the managed agent's behavior: read the announcement, check and apply each part in order, latch a failure with the entry that failed, and tear the table down, beneath a root of the caller's choice. The managed agent uses it too.
- A public renderer of an adapter launch's complete OpenVMM arguments, from its
PreparedLaunchand the launch's own inputs: the hypervisor, memory, kernel, initramfs, endpoints and report.LaunchSpeccan share it. - A public count of a program and its arguments as Windows quotes them, and a check of an adapter's launch against
PROCESS_COMMAND_LINE_LIMIT, with a documented reserve, so that planning can refuse a plan whose options leave the rest of the launch too little.
Downstream. Move the test adapter onto these. Once they are released, make sure that downstream users are updated to use them in place of their own copies.
Not in scope: the MAPS wire format, the managed launch's arguments, and the limit itself.
Metadata
Metadata
Assignees
Labels
No labels
Activity
ppenna commentedon Nov 1, 2026
#1071 delivered this issue's NVX work, which
devhas had since its merge commit 764b2da on October 31. The one task that #1071 left open, moving downstream adapters onto these APIs once a release includes them, is left to the downstream repositories, so I'm closing this issue as completed.What
devhas (checked at e92bfb5):nvx::guest::mappings::MappingTable, withTableErrorandRefusal, which the managed agent also uses (cd7c340). As nvx-rs: give adapters the host mapping table, the rest of a launch's arguments, and the command-line count #1071's design notes explain, the root that applied the mappings tears them down (Mapper::teardown,Root::teardown), not the table.VmmLaunch, whichLaunchSpec::openvmm_argumentsshares, andPreparedLaunch::adapter_arguments(17905e9).process_command_line_unitsandfit_process_command_line(e568670), andSandboxPlan::check_adapter_launchwith the documentedVmmLaunch::RESERVEof 2,048 UTF-16 code units (51b354a).MappingTable(af481bd). Its layered launch renders throughadapter_argumentsand checks its plan withcheck_adapter_launch(f50f626).CI run 41161285842 passed for #1071's head, f50f626.
Release. No release on crates.io has these APIs yet:
0.1.0-alpha.8, the newest, was published on October 31 at 05:44 UTC. Its.cargo_vcs_info.jsonrecords 23ad267, which predates nvx-rs: give adapters the host mapping table, the rest of a launch's arguments, and the command-line count #1071, and its sources hold noMappingTable,VmmLaunch,adapter_arguments, orcheck_adapter_launch.Package nvx cratefor an unrelated reason, nvx-rs: artifacts.json pins a release from before time ABI 2, so bundled builds and the nightlyPackage nvx cratefail #1173: the release thatartifacts.jsonpinned declared no time ABI. nvx-rs: bundle a release that declares time ABI 2 #1174 fixed it at c4acffb, which contains 764b2da. So the next passing nightly run, or a dispatch of CI ondev, publishes0.1.0-alpha.9, the first release with these APIs.Downstream. crates.io lists two crates that depend on
nvx,aci_edge_sandboxesandaci_edge_sandboxes_model0.1.0 from Azure/aci-edge-sandbox, both pinned tonvx =0.1.0-alpha.6. At Azure/aci-edge-sandbox@08708d1, their sources re-exportnvxbut use onlyresolve_guest_path, the error types,Hypervisor, andnetfrom it. They keep no copy of the table, the launch arguments, or the count. The agent library that their bundle ships, which drives OpenVMM, is not part of that repository's sources. GitHub code search fordecode_guest_maps_payload,--microvm-control-auth-stdin, andPROCESS_COMMAND_LINE_LIMITfound no other users outside NVX and its forks. The downstream repositories own the move onto these APIs, which can start once0.1.0-alpha.9is published.