feat(run): add explicit vmnet subnet

[wignerStan]

What changed

• Add tart run --net-vmnet-subnet <CIDR> on macOS 26 or newer.
• Create an independent shared-NAT vmnet logical network with VZVmnetNetworkDeviceAttachment.
• Configure the requested IPv4 subnet for every invocation, independent of port forwarding.
• Keep DHCP enabled so the guest receives an address from that subnet.
• Read the created subnet back with vmnet_network_get_ipv4_subnet and fail instead of silently continuing if vmnet did not honor the requested CIDR.
• Validate that the CIDR is canonical, fully contained in RFC 1918 address space, and has at least one guest-assignable address (/30 or larger).
• Make the new mode mutually exclusive with bridged, Softnet, and host-only networking.
• Add a dedicated development-signing entitlement set for local vmnet testing while leaving ordinary snapshot signing unchanged.
• Add unit coverage for CIDR parsing, mask derivation, returned-subnet verification, and invalid ranges.

Usage

tart run --net-vmnet-subnet 192.168.200.0/24 my-vm

This gives Tart a deliberate network range instead of relying on Apple's automatically selected shared vmnet range. VPN/TUN routing software can then distinguish the Tart range from unrelated virtualization networks and select its direct outbound for that traffic, while products such as Parallels can remain on their own network. The packet may still enter a TUN and be handled by a direct outbound; the useful property here is the deterministic range available to routing policy.

Motivation

The global com.apple.vmnet.plist override is not scoped to Tart and is reported as unreliable on Tahoe (#1225). Existing Tart network modes also do not provide a per-invocation explicit NAT subnet:

• default shared networking uses Apple's selected subnet;
• bridged networking uses the physical LAN;
• host-only networking has no Internet access;
• Softnet currently creates its vmnet shared interface with default subnet selection and has no explicit subnet argument.

This PR therefore uses the macOS 26 logical-network API only when an explicit subnet is requested. Existing shared networking and Softnet behavior are unchanged.

Difference from #1268

This is intentionally narrower:

• no port forwarding;
• no MAC-to-subnet hashing;
• no claim to replace Softnet;
• no subnet configuration conditional on another option.

The user supplies the CIDR directly, which is the feature needed for deterministic routing policy.

Implementation notes

For 192.168.200.0/24, Tart passes the canonical subnet address 192.168.200.0 and mask 255.255.255.0 to vmnet_network_configuration_set_ipv4_subnet. Apple's API reserves the first, second, and last addresses; the second address is used by the host and the remaining assignable addresses are available to DHCP.

After network creation, Tart retrieves the actual address and mask and verifies that they normalize to the requested CIDR. A different network or mask is rejected.

The vmnet configuration and network references are released through a small Core Foundation C shim. The network remains strongly owned by NetworkVmnet for the lifetime of the VM.

The feature is gated behind Swift 6.4/Xcode 27 and @available(macOS 26, *).

Development signing

Production signing already carries com.apple.vm.networking. For local source testing, scripts/run-signed.sh selects Resources/tart-vmnet-dev.entitlements when either --net-vmnet-subnet VALUE or --net-vmnet-subnet=VALUE is present. The repository's embedded development provisioning profile authorizes that entitlement.

Ordinary snapshot artifacts continue to use the normal development entitlement set. This keeps existing snapshot binaries runnable in hosted environments, but those ordinary snapshots cannot exercise --net-vmnet-subnet.

Validation

Validated from feature head 43978042b895d0dd8dcb1a2243c9c2187cb1af36 on an xcode-27-arm64 runner with macOS 26.5.2 and Swift 6.4:

• swift build --build-system swiftbuild passed.
• Full Swift unit suite passed: 161 tests executed, 31 environment-dependent skips, 0 failures.
• NetworkVmnetTests passed: 9 tests, 0 failures.
• SwiftFormat passed with no required changes.
• The Xcode 27 SDK header confirms that the setter parameter is the subnet address, not the host address.
• Configuration-setter probes accepted the advertised private-range boundaries and /30: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 192.168.200.0/24, and 192.168.200.0/30.
• The embedded development provisioning profile contains com.apple.vm.networking = true.
• Codex code review on 43978042 found no major issues.

A hosted attempt reached vmnet_network_create but returned status 1002 in that restricted runner environment. This is not counted as either a runtime pass or a product-code failure. No complete real-machine VM boot result is currently recorded on the PR.

A full Tart VM smoke test on a real macOS 26 Apple Silicon host is still required before merge. It should verify guest DHCP assignment, tart ip (including lease-file behavior), host-to-guest reachability, DNS and Internet access, IPv6 behavior, conflicting/subsequent network creation, and the sing-box direct rule while confirming the Parallels CIDR remains unaffected.

[wignerStan]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T07:23:18.575625Z	4397804	Draft marked ready
🔒 Security Review	✅ Completed 2026-09-06T07:25:36.970368Z	4397804	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: 6147f96d1d

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6147f96d1d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[wignerStan]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: a781ac09b2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: a781ac09b2

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[wignerStan]

Validation evidence for a781ac0:

• Xcode 27 / macOS 26.5.2 / Swift 6.4 build and all 8 NetworkVmnetTests passed: https://github.com/wignerStan/tart/actions/runs/33267865944
• A follow-up signed-helper run again passed the build, tests, entitlement check, and strict codesign verification. The GitHub-hosted runner then terminated the standalone vmnet helper with SIGKILL, so I am not counting that as a runtime pass: https://github.com/wignerStan/tart/actions/runs/33268061195
• Codex code and security review completed on a781ac0 with no remaining findings.

The full guest DHCP / tart ip / Internet smoke therefore remains for a Tart-capable persistent worker.

[wignerStan]

@codex review

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: 6b8776becb

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 6b8776becb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[wignerStan]

Validation and test artifact update for 6b8776b:

• Reviewed the vmnet lifecycle, DHCP behavior, CLI validation, signing, and tart ip resolver path.
• Added post-create subnet verification using vmnet_network_get_ipv4_subnet; Tart now fails clearly if vmnet returns a different network or mask.
• Added regression coverage accepting either a returned network address or gateway address while rejecting a different CIDR.
• Latest Codex code review found no major issues; latest security review found no security issues.
• Full Swift suite passed: 161 tests executed, 31 environment-dependent tests skipped, 0 failures.
• NetworkVmnetTests: 9 passed, 0 failures.
• SwiftFormat: clean.
• Apple Silicon release CLI and --net-vmnet-subnet help registration verified before signing.
• Signed app bundle passed strict codesign verification and contains com.apple.vm.networking.

GitHub Actions build: https://github.com/wignerStan/tart/actions/runs/33282954364

Artifact name: tart-vmnet-subnet-arm64-411d43f2a0817532b1a0deb6d13e97fb21018e81

The artifact contains a development-signed tart.app, embedded provisioning profile, entitlement file, resign-local.sh, and test instructions. A real macOS 26 Apple Silicon smoke test should verify guest DHCP assignment, tart ip (with ARP/agent fallback if necessary), Internet access, and a sing-box destination rule selecting direct for the requested CIDR.

[wignerStan]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: f877ab8057

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: f877ab8057

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[wignerStan]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: 4f6954dc7f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: 4f6954dc7f

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[wignerStan]

@codex review

Please rigorously review the current head 43978042b895d0dd8dcb1a2243c9c2187cb1af36 (not the previously reviewed commit). Focus on the Xcode 27 vmnet API contract, IPv4 subnet/address byte order, Core Foundation ownership, Virtualization attachment lifetime, macOS availability gates, signing/entitlement paths, CLI validation, DHCP/IP discovery, and collision/error handling.

[wignerStan]

@codex security review

Please review the current head 43978042b895d0dd8dcb1a2243c9c2187cb1af36, especially restricted entitlement handling, embedded provisioning-profile use, CIDR parsing, unsafe pointer/CF lifetime boundaries, and whether user-supplied subnet input can cause unsafe or privilege-sensitive behavior.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 43978042b8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Security review completed. No security issues were found in this pull request.

Reviewed commit: 43978042b8

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[wignerStan]

Follow-up review and corrected test build

I reviewed the follow-up commits and the complete current diff again at head 43978042b895d0dd8dcb1a2243c9c2187cb1af36.

Correctness issue fixed

The previous head passed the first host address (192.168.200.1) to vmnet_network_configuration_set_ipv4_subnet. The Xcode 27 SDK contract requires the canonical subnet address (192.168.200.0). This is fixed by:

• b227e968368a93a4d2258a8bc92af208fb9573e2 — pass the subnet address to vmnet;
• 43978042b895d0dd8dcb1a2243c9c2187cb1af36 — update regression coverage.

The PR description has also been corrected; it no longer documents the old .1 behavior.

Validation

GitHub Actions run 33426086990 completed successfully on the xcode-27-arm64 macOS 26.5.2 runner. Every step passed:

• exact feature-source verification;
• Xcode 27 vmnet SDK-contract verification;
• embedded provisioning-profile authorization for com.apple.vm.networking;
• canonical subnet setter probe;
• full Swift build and unit suite: 161 executed, 31 environment-dependent skips, 0 failures;
• NetworkVmnetTests: 9 passed, 0 failures;
• SwiftFormat;
• Apple Silicon release build;
• strict app-bundle code-signature and entitlement checks;
• artifact upload.

A separate configuration probe confirmed that the setter accepts all advertised boundary shapes: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 192.168.200.0/24, and 192.168.200.0/30.

Codex code review on 43978042 found no major issues. Codex security review on the same commit found no security issues.

The uploaded artifact is tart-vmnet-subnet-arm64-43978042 (artifact ID 9771035389). GitHub recorded the outer Actions archive digest as:

sha256:bea23e30cad02b7b530b91a2427e1f34158477d0ed3afe6beba90f7de8b4bf37

The packaged Mac test bundle itself has:

26a8d3e2fc53f12ea551c97d6caa0f9f0b2741d0bc184ef5f831191d34165cff  tart-vmnet-subnet-arm64.zip

Real-machine status

There is still no complete physical/real-machine VM boot result recorded on this PR. A hosted probe reached vmnet_network_create but returned status 1002 in the restricted runner, so it is not treated as a runtime pass or as a product failure.

The real macOS 26 Apple Silicon test should record:

1. guest DHCP address and gateway in the requested CIDR;
2. default tart ip behavior and fallback resolvers;
3. host-to-guest reachability;
4. guest DNS and IPv4 Internet access;
5. guest/host IPv6 addresses and routes;
6. repeated and conflicting subnet creation behavior;
7. sing-box selecting direct for the Tart CIDR while the Parallels CIDR remains unaffected.

The PR should remain draft until that test is attached.