[Request]: Native USB Passthrough via VZXHCIController (macOS 15+)

[beriberikix]

Feature or enhancement request details

Currently, passing physical USB devices into apple/container environments is not natively supported. While there are ongoing community discussions about network-based workarounds like USB/IP (see #640 and apple/containerization#74), I would like to formally request native USB passthrough utilizing the VZXHCIController and VZUSBDevice APIs introduced in macOS 15's Virtualization.framework.

The Use Case (Embedded Development):

Developers working with embedded systems (microcontrollers, ESP32, STM32, Arduino, Raspberry Pi Pico) rely heavily on direct USB access to the guest OS for:

1. Serial Communication: Interacting with UART bridges (FTDI, CP2102, CH340).
2. Debugging: Low-latency JTAG/SWD connections via tools like OpenOCD or probe-rs.
3. Flashing: Handling rapid USB disconnect/reconnect cycles triggered by bootloaders during the flashing process.

Being able to map a host USB port directly to an apple/container instance would allow us to run complex embedded toolchains entirely within Linux containers, without polluting the macOS host environment.

Why USB/IP Workarounds Fall Short:

As the author of usbipd-mac, I have been heavily invested in the USB/IP route. However, relying on USB/IP for this workflow introduces significant friction:

• Host Daemons & Entitlements: Running a native USB/IP server on macOS requires System Extensions and highly restricted DriverKit entitlements (which currently block seamless distribution). User-space Python alternatives often require sudo to detach host drivers.
• Latency: JTAG debugging is highly sensitive to latency, and pushing the protocol over a virtual network stack introduces noticeable overhead compared to memory-mapped xHCI.
• Kernel Requirements: It forces users to compile custom container kernels to enable vhci-hcd.

Technical Implementation & Known Blockers:

Implementing this would require:

• Instantiating a VZXHCIController in the apple/containerization VM configuration.
• Exposing a CLI flag to map a specific host device (e.g., --usb vendor=0x0403,product=0x6001).
• The Entitlement Barrier: I recognize that for Virtualization.framework to intercept USB devices, the executing binary must possess the com.apple.vm.device-access entitlement.

I understand that adding this entitlement to a CLI tool involves security and UX considerations (such as handling headless permission prompts). However, solving this would make apple/container a massively powerful, native replacement for heavier VM managers in the embedded hardware space.

Thank you to the maintainers for the incredible work on this project so far!

Code of Conduct

• I agree to follow this project's Code of Conduct

[dcantah]

The VZ APIs (VZXHCIController and pals) only offer the ability to expose virtual mass storage devices backed by some host-side disk image. They don't offer USB passthrough unfortunately

[beriberikix]

@dcantah thanks for the clarification - I couldn't figure out what's supported at the moment, but that makes sense. Sounds like the best path at the moment is indeed is apple/containerization#74. It would be great if Apple decided to implement a native USB/IP server in the same way we have an official option Windows from Microsoft.

My attempt with https://github.com/beriberikix/usbipd-mac was unfortunately a failure because I wasn't able to get an entitlement. So hopefully an internal team would have less issues getting privileged access 🤞