USB devices

OrbStack can pass USB devices through to Linux, so hardware plugged into your Mac shows up inside your machines and containers. This works with serial/UART adapters, security keys, USB Ethernet and Wi-Fi adapters, Android phones, flash drives, SDRs, lab instruments, and most other USB devices.

Serial/UART devices and security keys can even be shared with Linux without disconnecting them from macOS, a capability unique to OrbStack.

Use cases

USB passthrough lets you use Linux's drivers and tools with real hardware, which opens up things that aren't possible on macOS:

• Hardware development and debugging over serial/UART and similar interfaces
• Android development with adb and fastboot
• Wi-Fi penetration testing with adapters that support monitor mode and packet injection
• Mounting Linux file systems like ext4 and Btrfs from USB flash drives and disks
• Anything else that needs Linux drivers or tooling

Forwarded vs. dedicated

OrbStack handles devices in two ways:

• Forwarded: Serial/UART adapters and FIDO security keys are shared with Linux while staying usable on macOS, so you can use them in both at the same time. Unlike normal passthrough, the device is never disconnected from your Mac.
• Dedicated passthrough: Any other USB device can be passed through to Linux exclusively. While attached, it's taken away from macOS until you detach it.

Devices tab

Open the Devices tab in the OrbStack app to see all connected USB devices, grouped by how they're shared:

• Forwarded: serial/UART ports and security keys, available to both macOS and Linux
• Passthrough: devices currently dedicated to Linux
• Not shared: devices only in use by macOS

Select a device to see its details, such as type, vendor/product ID, speed, and serial number. Use Attach to pass a device through to Linux and Detach to return it to macOS. Attaching a forwarded device (serial port or security key) for dedicated passthrough asks you to confirm first, since it takes the device away from macOS.

Command line

You can also manage USB passthrough from the terminal:

# List connected USB devices
orb usb list

# Show details for a device
orb usb info <id>

# Attach a device to Linux
orb usb attach <id>

# Detach a device
orb usb detach <id>

Use the ID from the first column of orb usb list. Attached devices are available to all of your (non-isolated) machines and containers, since they share one Linux instance.

For USB network adapters, you can choose which machine the network interface joins with -m:

orb usb attach <id> -m ubuntu

Serial & UART devices

Serial and UART ports connected to your Mac, such as USB-to-serial adapters, are automatically forwarded to Linux and appear as character devices in the guest. They stay usable on macOS at the same time.

List them with:

orb serial list

Security keys

FIDO/U2F security keys (e.g. YubiKeys) are automatically forwarded to Linux, so you can use them for SSH, sudo, and WebAuthn inside your machines while they remain available to macOS apps like your browser.

Forwarding only covers the FIDO/U2F (HID) interface, not CCID/smart card functions like PIV or GPG. To use those in Linux, attach the key with dedicated passthrough instead.

Limitations

• Devices aren't available in isolated machines.

Tested devices

To give you an idea of what devices should work, the following devices have been tested with OrbStack:

Miscellaneous

• Lexar USB Flash Drive
• Google Pixel 6 (adb/fastboot)
• YubiKey 5C NFC (FIDO/HID, CCID, ykman)

Serial/UART

• Adafruit USB to TTL Serial Cable (Prolific PL2303)
• USB to TTL Serial Adapter (Silicon Labs CP2102)
• DSD TECH USB to TTL Serial Adapter (Silicon Labs CP2102N)
• Gearmo USB to Serial RS-232 Adapter (FTDI FT232R)

Ethernet

• Amazon Basics USB-C 1GbE Ethernet Adapter (ASIX AX88179A)
• Plugable USB-C 5GbE Ethernet Adapter (Realtek RTL8157)

Wi-Fi

• EDUP USB WiFi 6E Adapter (Mediatek MT7921U)
• TP-Link Wireless N USB Adapter (Realtek RTL8192CU)
• TP-Link Wireless N USB Adapter (Realtek RTL8188CUS)
• TP-Link TL-WN727N Wireless N USB Adapter (Ralink RT5390)

Most devices not explicitly listed should work. Please open an issue if you find a device that doesn't work.