nvx-run

# Run NVX Boot NVX in the appropriate local or remote execution context and verify guest behavior. ## 1. Choose the Execution Context Use the current local workspace when the user requests local execution or the local host provides the required backend. Use SSH when the user names a remote host, the required backend is unavailable locally, or the target machine itself matters. For local execution: - Run from the NVX repository root. - Record the OS, `git rev-parse HEAD`, and `git status --short`. - Run `python3 scripts/nvx.py verify` on Linux or `python scripts\nvx.py verify` on Windows. - Select `kvm` or `mshv` on Linux and confirm the matching device is readable and writable. Select only `whp` on Windows. - Preserve a dirty checkout and report it. Do not silently change revisions or replace artifacts. For SSH execution, load and complete [nvx-host-connect](../nvx-host-connect/SKILL.md), then reuse its persistent session, repository directory, backend, revision, and artifact provenance. Keep standard input attached to the guest; use `ssh -tt` if opening a direct interactive command. Use `nvx-rs run` rather than invoking OpenVMM directly: the checkout's `nvx-rs/target/release/nvx-rs`, or `nvx-rs\target\release\nvx-rs.exe` on Windows. Build it from the repository root first, and again when the task changes `nvx-rs`: ```console cargo build --release --locked --features cli --manifest-path nvx-rs/Cargo.toml --target-dir nvx-rs/target ``` If artifacts are missing, choose an explicit `nvx-rs download --hypervisor <backend>` for packaged artifacts or the relevant build command for checkout changes. A run in a checkout that holds no artifacts downloads them itself, and one that holds some of them warns instead; set `NVX_AUTO_DOWNLOAD=0` to keep a run from downloading. Do not overwrite artifacts the user wants to preserve. ## 2. Assemble the Run Start with an explicit backend and add only options required by the task: ```bash backend=kvm # Use mshv when required. nvx-rs/target/release/nvx-rs run --hypervisor "$backend" --dry-run ``` ```powershell nvx-rs\target\release\nvx-rs.exe run --hypervisor whp --dry-run ``` Supported examples: ```bash nvx-rs/target/release/nvx-rs run --hypervisor kvm \ --memory-mib 256 --net 10.0.0.2/24 --network-profile portable \ --cmdline "quiet loglevel=0" nvx-rs/target/release/nvx-rs run --hypervisor mshv \ --mount "/mnt/host,/absolute/host/share,rw" ``` ```powershell nvx-rs\target\release\nvx-rs.exe run --hypervisor whp ` --mount "/mnt/host,C:\Users\me\microvm-share,rw" ``` For `--mount`, the guest target must be an absolute Linux path. The mode follows the last comma, so a host path may contain commas when the mode is given. Use `ro` unless guest writes are required. ## 3. Check for Conflicts Immediately before booting, check for an existing OpenVMM process in the selected execution context: ```bash pgrep -af openvmm || true ``` ```powershell Get-Process openvmm -ErrorAction SilentlyContinue ``` Do not start a competing VM unless the user confirms the existing process is expected and the host has sufficient resources. Never terminate a process the current session did not start. ## 4. Run Interactively ```bash backend=kvm # Use mshv when required; append the approved options. nvx-rs/target/release/nvx-rs run --hypervisor "$backend" ``` ```powershell # Append the options approved from the dry run when needed. nvx-rs\target\release\nvx-rs.exe run --hypervisor whp ``` Success requires the guest's `NVX-GUEST-BOOT-OK: <guest>` marker, such as `NVX-GUEST-BOOT-OK: alpine` for the default guest, and a responsive root shell. Exercise the requested behavior, then exit cleanly inside the guest: ```sh /sbin/nvx-exit 0 ``` Record the host process exit status. If the guest hangs, interrupt only the command started by the current terminal or SSH session and preserve its output. Do not issue a host-wide `killall` or an unscoped `Stop-Process`. ## Report Report whether execution was local or SSH, the host, backend, commit, dirty status, artifact source, exact run command, boot marker result, guest checks, and host exit status. For a failure, preserve the terminal output and continue with [nvx-debug](../nvx-debug/SKILL.md).