USB & Target Boards¶

Alloy Host can pass USB devices (debuggers, boards, programmers) from your host into a VM or WSL2 environment. USB is not supported on the docker backend—use vm or wsl2, or map devices with docker run --device outside alloy-host.

Prerequisites¶

VirtualBox (macOS / Linux / Windows host)

USB passthrough uses VirtualBox. On Linux, add your user to vboxusers:

sudo usermod -aG vboxusers $USER
# log out and back in

Run alloy-host on the host OS (Windows, macOS, or Linux)—not only inside WSL without usbipd setup.

WSL2 (Windows host)

Install usbipd-win on Windows and attach devices to WSL before using alloy-host inside WSL:

winget install usbipd

After installing, reboot. From an elevated PowerShell:

usbipd list
usbipd bind --busid <BUSID>
usbipd attach --wsl --busid <BUSID>

Then use alloy-host usb from your WSL distro.

Docker backend

Not supported. Use --backend vm or wsl2 for on-target debug and flash.

List connected USB devices¶

alloy-host usb list

With a VM name, see which devices are already attached to that environment:

alloy-host usb list arm-dev

Output is a text block per device (vendor/product, bus ID, attachment state)—not a fixed column table.

Attach a device¶

Syntax: alloy-host usb attach <device> [name]

<device> is a number from usb list, a partial name, or a bus ID.

alloy-host usb attach 1 arm-dev
alloy-host usb attach "J-Link" arm-dev

Inside the VM, verify with lsusb after alloy-host ssh arm-dev.

Flash firmware¶

alloy-host ssh arm-dev
# inside the guest:
lsusb
JLinkExe -device nRF9160 -if SWD -speed 4000 -commandfile flash.jlink

Detach a device¶

alloy-host usb detach 1 arm-dev
alloy-host usb detach "J-Link" arm-dev

Check attachment status¶

alloy-host usb status

Shows attachments across environments (no VM name argument).

Troubleshooting¶

Device not visible in the guest

alloy-host usb detach 1 arm-dev
alloy-host usb attach 1 arm-dev

Linux permission denied

Install udev rules for your debugger in the blueprint (see Extending blueprints).

WSL2 on Windows

Complete the usbipd bind / attach --wsl steps in PowerShell before alloy-host usb attach in WSL.