Repository navigation
nvx-rs slimming, phase 3.1: the CLI switches to the new interface #1083
Description
Parent: #1076. Phase: 3, NVX's own binaries on the new interface. Needs: #1080; inside phase 3, groups of #1084, #1085 (see the table below). Unblocks: inside phase 3, groups of #1084, #1085; #1086, #1087, #1089, #1090. The lanes of phase 3 meet at group level, never in a cycle: each group issue names the groups that it needs.
Goal. The CLI stays in host::cli, hidden since #1077, with its cli feature. It switches to the new interface in dependency-closed command groups, switching a launch's records and every command that reads them together, on a sandbox store of its own, until it uses none of nvx's old launch, store or config APIs. The CLI may change its output: behavior tests replace compatibility checks.
Today (dev e42b1795) and after:
| Area | Today | After |
|---|---|---|
| The CLI | host::cli, behind the cli feature and hidden from the public API. |
The same module and feature, on the new interface only. |
| Its state | host::store. |
host::cli::store: the layout, the lock, the launch journal written before the spawn, the runtime record that holds SavedVm, the capability file, the log claim, the endpoint-owner lookup and the recovery of interrupted launches. |
run |
Builds OpenVMM's arguments directly, through the old share helpers and the foreground launcher, without OpenVMM's lifecycle or workload-identity flags. | A VmConfig with the CLI's own guest tokens (the blockless mode, the entrypoint and its arguments, the workload identity and nvx_share), and shares planned through the export planner (#802). |
sandbox |
EROFS over a scratch or a RAM upper whose tmpfs takes the kernel's default size, half the guest's RAM, with no cap of its own. | EROFS or GPT, over a scratch or a RAM upper with its cap. start and sandbox run send nvx_sandbox=1 and no OpenVMM lifecycle token, so their layered roots boot through nvx-init. Protected paths are refused, by canonical path, at provision and at start, and sandbox run checks the ones that apply (#818). sandbox run takes provision's image and upper options and exec's options, has no state directory, and is a cold boot, one exec and a stop. |
| Exec admission | None. | A per-sandbox OS file lock: sandbox exec waits for it up to --wait (60 s by default), then fails with busy (#819). |
| Limits | --memory-max and --pids-max. |
Gone: the VM is the limit. |
| Other old dependencies | The downloads use host::supervisor::spawn_command, and session uses host::supervisor::Launched; option parsing calls parsers in nvx. |
The downloads spawn their tools without the supervisor; session uses neither host::instance nor the supervisor; the CLI parses native egress rules, loopback forwards, proxy endpoints and decimals itself. |
Groups, in order. Each group issue lists its PRs, with their goals, contents, Needs and estimates.
| Group issue | Delivers | PRs | Needs |
|---|---|---|---|
| #1108 | The CLI keeps its own sandbox store | SL3.2a, SL3.2b, SL3.3a, SL3.3b | #1100 |
| #1109 | run uses the new interface and the CLI's own guest tokens |
SL3.4a1, SL3.4a2 | #1100 |
| #1110 | The sandbox lifecycle runs on the new interface and nvx-init | SL3.5d, SL3.5b, SL3.5a, SL3.5c | #1108, #1109, #1117 |
| #1111 | A managed sandbox run, and one exec at a time |
SL3.4b, SL3.9 | #1110, #1117 |
| #1112 | The CLI uses only the new interface | SL3.10a, SL3.10b, SL3.11a | #1110, #1111, #1114 |
Notes.
- Nothing moves first. The CLI and its current integration tests stay where they are. New internal code goes under
host::cli:store,snapshots,exec_lockandguest_tokens. - Program-only dependencies stay private. The helpers that phase 4 makes private to the CLI remain where they are and keep their
cligates; the CLI calls them directly. scripts/nvx.pystays the developer tool, and drives the existingnvx-rsbinary. Its checks test the new behavior and record their remaining outputs again.
Tests. Each PR keeps, rewrites or retires each existing test of its area, by name. The CLI's integration tests keep CARGO_BIN_EXE_nvx-rs and CARGO_BIN_EXE_nvx-fake-openvmm. The store: its layout and lock, the journal written before the spawn, the saved reattach values, the log claim and the endpoint-owner lookup, and the recovery or cleanup of an interrupted launch. run: both blockless modes, the CLI's guest tokens, shares from the export planner, and no OpenVMM lifecycle or workload-identity flag. sandbox: EROFS and GPT, with a scratch or a capped RAM upper; start and sandbox run send nvx_sandbox=1 and no OpenVMM lifecycle token, and boot through nvx-init; the protected-path refusals at provision, start and sandbox run; reattach with the runtime identity check; a graceful stop, and a forced one after the grace period; deprovision removes every record, claim and VM file. The exec lock: the wait, the 60 s default and busy. The CLI's own option parsers. nvx.py drives the existing binary; its checks test behavior rather than the old output, and its remaining recorded outputs are recorded again.
Done when: every group issue is closed; the CLI uses none of nvx's old launch, store, config, instance or supervisor APIs; and it parses its own options.
Activity
nvxa library of mechanisms and value types #1076clifeature is gone #1107runuses the new interface and the CLI's own guest tokens #1109sandbox run, and one exec at a time #1111[-]nvx-rs slimming, phase 3.1: nvx-cli: the old CLI moves out, then switches to the new interface[/-][+]nvx-rs slimming, phase 3.1: the CLI switches to the new interface[/+]clifeature is gone #1107ppenna commentedon Nov 12, 2026
Completed. Every group of this phase is closed:
runuses the new interface and the CLI's own guest tokens #1109,runuses the new interface and the CLI's own guest tokens.sandbox run, and one exec at a time #1111, a managedsandbox run, and one exec at a time: SL3.4b sandbox: run a workload once through the managed VM API (SL3.4b) #1490, SL3.9 cli: serialize sandbox exec admission across CLI processes (SL3.9) #1469.#1106 and #1107 were closed as not planned.
Passing CI that contains all of them: the push run on
feature/nvx-refactoratff15032cdc5, https://github.com/microsoft/nvx/actions/runs/43198442034.