feat: NVX integration design doc by huzaifa-d · Pull Request #1448 · microsoft/mxc

Huzaifa Danish (huzaifa-d) · 2026-10-07T19:34:43Z

📖 Description

Documents the proposed NVX integration in MXC.

✅ Checklist

Signed the Contributor License Agreement
Linked to an issue
Updated documentation (if applicable)
Updated Copilot instructions (if build, architecture, or conventions changed)
If this PR changes Cargo.lock, the dependency-feed-check check passes (see docs/pull-requests.md)

📋 Issue Type

Bug fix
Feature
Task

Microsoft Reviewers: Open in CodeFlow

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

azure-pipelines · 2026-10-07T19:34:53Z

Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Enhance NVX integration documentation with detailed updates on state-aware process lifetime, discovery payloads, lifecycle management, SDK behavior, filesystem access, and network rules. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

🔵 Needs a closer look

The design must preserve existing Linux MicroVM behavior and define OCI image platform selection.

0 open findings

1 resolved since last review

Contain OCI parsing and extraction against hostile images

Previously missed (2)

In code that hasn't changed since last review

Preserve Linux NanVix routing while limiting NVX to Windows x64

docs/nvx-integration.md:22

The unconditional replacement drops an existing platform path: mxc_engine currently routes microvm to NanVix on Linux as well as Windows (src/core/mxc_engine/src/run.rs:294-307,349-370), and the Linux runner uses KVM. Since section 7 limits the initial NVX integration to Windows x64, define whether Linux keeps NanVix until NVX support arrives (and retain Linux coverage) rather than silently making microvm unavailable there.

Select and validate linux/amd64 OCI manifests deterministically

docs/nvx-integration.md:798

Digest resolution alone does not define which manifest to choose from a multi-platform OCI index. The host is Windows x64 but the guest is Linux, so host-platform selection can choose an unusable windows/amd64 image; ARM-only and Windows-only references also need a deterministic rejection. Make linux/amd64 selection and platform validation part of the conversion contract.

🧠 Review effort: Balanced

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

Pedro Henrique Penna (ppenna) · 2026-10-08T17:34:59Z

+Negative filesystem and network tests must include a working positive control
+so infrastructure failures are not mistaken for policy enforcement.
+
+## 9. Long-term plan


Should we mention Linux and MacOS support?

Gudge (MGudgin) · 2026-10-08T14:15:21Z

+live: a guest write changes the mapped host file immediately. Denied entries
+are hidden by OpenVMM within the exported host tree.
+
+All mapped paths must exist, be on the same Windows volume, and share a common


Why these restrictions around volume and shared common directory? Why can't I map file paths on both c:\ and d:? Why can't I map c:\etc\src\git\myrepo and c:\users\gudge\mydocs ?

From what I understand, these are NVX restrictions. Pedro Henrique Penna (@ppenna), could you please opine?

This is not a NVX limitation. NVX runs Linux as a guest and Linux have all paths under /. We cannot have a separate root per construction.

Gudge (MGudgin) · 2026-10-08T14:17:07Z

+aci-edge-sandboxes:<32 lowercase hexadecimal characters>
+```
+
+MXC will register the `aci-edge-sandboxes:` prefix in native lifecycle


Why doesn't this string contain 'nvx' somewhere?

From what I understand, these is NVX implementation. Pedro Henrique Penna (@ppenna), could you please opine?

Gudge (MGudgin) · 2026-10-08T15:20:26Z

+
+## 7. Windows requirement
+
+The initial implementation will support Windows x64. Windows ARM is planned


Why the ARM restriction?

No restriction, just current short-term plan for v1.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Several documented capabilities and outcome mappings conflict with current NVX and MXC contracts.

3 open findings

Document NVX filesystem compatibility limits · New
Clarify OCI writable-layer persistence semantics · New
Define timeout mapping for relayed state-aware execution · New

🧠 Review effort: Balanced

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Lifecycle registration and registry-policy migration remain incomplete, with additional NVX limits missing from the documentation and test plan.

4 open findings

Define NVX registry policy and fail-closed migration precedence · New
Expose build helper through a supported versioned module · New
Register MicroVM lifecycle version and request roots · New
Document NVX's 16 KiB denied-path limit · New

3 resolved since last review

Define timeout mapping for relayed state-aware execution
Clarify OCI writable-layer persistence semantics
Document NVX filesystem compatibility limits

🧠 Review effort: Balanced

+The policy will be stored under
+`HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Mxc` with the following behaviour:
+
+| Policy state | Behaviour |
+| --- | --- |
+| Value absent | Unmanaged; any registry host may be contacted |
+| One or more hosts | Only those registry hosts may be contacted |
+| Present but empty | No registry may be contacted |
+| Present but unreadable | No registry may be contacted |


+    mxc_sdk_build::stage_nvx_runtime()
+        .expect("failed to stage the NVX runtime");


+1. Add `microvm.image`, `microvm.memoryMb`, state-aware MicroVM provision,
+   engine binding, and runtime tests to the development `1.1.0-alpha`
+   contract.


+
+| Current NVX filesystem limit | Behaviour |
+| --- | --- |
+| Denied paths | At most 128 hidden paths |


Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

huzaifa-msft and others added 5 commits October 6, 2026 10:58

Document NVX integration design

71f40fe

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Fix NVX document whitespace

bc3a1f4

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Refine NVX integration proposal

e1162a8

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Expand NVX image integration design

cef0da9

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Complete NVX developer integration proposal

a74c7b4

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 7, 2026 19:34

Copilot started reviewing on behalf of Huzaifa Danish (huzaifa-d) October 7, 2026 19:35 View session

This comment was marked as resolved.

Sign in to view

Address NVX document review feedback

25130c3

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 7, 2026 20:32

Copilot started reviewing on behalf of Huzaifa Danish (huzaifa-d) October 7, 2026 20:32 View session

This comment was marked as resolved.

Sign in to view

Address NVX integration review gaps

275db14

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 7, 2026 21:25

Copilot started reviewing on behalf of Huzaifa Danish (huzaifa-d) October 7, 2026 21:26 View session

This comment was marked as resolved.

Sign in to view

Clarify NVX SDK deployment contracts

db3d0ca

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 7, 2026 21:45

Copilot started reviewing on behalf of Huzaifa Danish (huzaifa-d) October 7, 2026 21:46 View session

This comment was marked as resolved.

Sign in to view

Copilot AI balanced review requested due to automatic review settings October 7, 2026 22:06

Copilot started reviewing on behalf of Huzaifa Danish (huzaifa-d) October 7, 2026 22:07 View session

Unify NVX runtime package ownership

7748258

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

This comment was marked as resolved.

Sign in to view

Copilot AI balanced review requested due to automatic review settings October 7, 2026 22:11

Copilot started reviewing on behalf of Huzaifa Danish (huzaifa-d) October 7, 2026 22:14 View session

This comment was marked as resolved.

Sign in to view

Preserve NVX NuGet runtime layout

712e168

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 7, 2026 23:09

Copilot started reviewing on behalf of Huzaifa Danish (huzaifa-d) October 7, 2026 23:10 View session

Huzaifa Danish (huzaifa-d) changed the title ~~Document NVX integration design~~ feat: NVX integration design doc Oct 7, 2026

Huzaifa Danish (huzaifa-d) marked this pull request as ready for review October 7, 2026 23:13

Huzaifa Danish (huzaifa-d) requested a review from a team as a code owner October 7, 2026 23:13

Copilot AI reviewed Oct 7, 2026

View reviewed changes

Huzaifa Danish (huzaifa-d) commented Oct 8, 2026

View reviewed changes