FEATURES

USB devicesBeta

A container can use a USB device plugged into your computer: a USB serial adapter, a Zigbee or Z-Wave stick for Home Assistant, an Arduino or ESP32, a mouse or a keyboard. In the container it is an ordinary Linux device, such as /dev/ttyUSB0, that you pass in with docker run --device. USB support is in beta.

How it works on a Mac

Containers on a Mac run in Kiri’s Linux VM, and the VM has no USB port of its own. So Kiri takes the device away from macOS and passes its USB traffic into the VM. Linux there sees a USB device as if it were plugged into a Linux PC, loads its usual driver, and creates the device file a container can use.

How a USB device reaches a container on a MacYour MacKiri’s VMUSB deviceZigbee stickUSB helpertakes it from macOSvsockUSB/IPLinux USBits usual drivercontaineryour app/dev/ttyUSB0–deviceDetach, unplug or Stop, and the device goes back to macOS.
A device attached to Kiri. macOS lets go of it, Kiri carries its USB traffic into the VM, and the VM's Linux gives it a device file that you pass to a container.

Taking a device from macOS needs an administrator, so the first time you attach one, macOS asks for your password to install Kiri’s USB helper. After that, attaching doesn’t ask again. The helper only takes requests from your user account. After a Kiri update, the next attach asks once more, to replace the helper with the new version.

While a device is attached, only Kiri can use it: a mouse stops moving your cursor, and a serial port disappears from the Mac’s /dev. The VM also stays awake while a device is attached, instead of sleeping when no container runs. Up to 8 USB 2 devices and 8 USB 3 devices can be attached at once.

Attach a device

  1. Plug the device in, then open USB in the sidebar of Kiri’s window, under Kiri. It lists every USB device on your Mac, with an icon for its kind (mouse, keyboard, serial port, radio, network adapter and so on) and On this Mac or In Kiri.

  2. Press Attach on the device. The first time, enter your password to install the USB helper. The row turns to In Kiri.

  3. Pass it to a container with --device, using the name it has in the VM (see Which device file):

    docker run -d --name homeassistant --device /dev/ttyUSB0 \
      ghcr.io/home-assistant/home-assistant:stable
  4. When you’re done, press Detach. The device goes back to macOS, which uses it again as before.

Kiri
DockerContainersImagesVolumesNetworksBuildsKiriUSB · BetaShareSettings

USB

USB passthrough is in beta.
Sonoff Zigbee 3.0 Dongle10c4:ea60In KiriDetach
Arduino Uno2341:0043On this MacAttach
Logitech Receiver046d:c52bOn this MacAttach
The USB section on a Mac. The Zigbee stick is in Kiri and can be detached; the other devices are still the Mac's. The count beside USB in the sidebar is how many devices are in Kiri.

A device also goes back to macOS by itself when you press Stop in the window or Kiri’s engine stops. Updated · 0.2.1Unplugging it doesn’t give it back for good: Kiri waits for it. The list follows plugs and unplugs within a few seconds.

From the command line

kiri usb does the same from a terminal. A device is named by its location, its vendor:product ID, or part of its name:

zsh
$ kiri usb list
LOCATION     ID         SPEED  STATE      KIND      NAME
0x01100000   10c4:ea60  full   on the Mac radio     Sonoff Zigbee 3.0 USB Dongle Plus
0x02142300   2341:0043  full   on the Mac serial    Arduino Uno
$ kiri usb attach zigbee
Sonoff Zigbee 3.0 USB Dongle Plus is in Kiri now. In a container: --device /dev/ttyUSB0 (serial), /dev/input (HID) or /dev/bus/usb (raw).
It is gone from the Mac until `kiri usb detach 0x01100000`.
$ kiri usb detach 10c4:ea60
Sonoff Zigbee 3.0 USB Dongle Plus is back on the Mac.
Command What it does
kiri usb, kiri usb list or kiri usb ls Lists the USB devices, with their kind and whether each is in KiriNew · 0.2.1, or waiting for one to come back.
kiri usb attach DEVICE Passes a device through to the VM. The first time, it asks for your password to install the USB helper.
kiri usb detach DEVICE Gives a device back to macOS. New · 0.2.1For a device Kiri is waiting for, give its location: Kiri stops waiting.
kiri usb helper remove Removes the USB helper. Uninstalling Kiri removes it too.

When a device drops off

A device can leave the Mac’s USB bus without anyone detaching it. A board such as an ESP32 resets and shows up again, macOS takes USB devices off the bus while it sleeps, or you pull the cable out. Kiri then keeps the device on a waiting list. When the same device comes back, Kiri attaches it to the VM again by itself, without asking for your password, and your container’s --device path works again.

Kiri knows it is the same device by its vendor:product ID and its serial number, or its USB port when it has no serial number. It stops waiting when you detach the device, press Stop, or the engine restarts. A device that drops off within 5 seconds of attaching five times in a row, or fails to attach five times, is left on the Mac with a warning.

Kiri
KiriUSB · BetaShareSettings

USB

ESP32-S3303a:1001Waiting to come backStop waiting
Kiri attaches it again when it’s back. Stop waiting to leave it on this computer.
Sonoff Zigbee 3.0 Dongle10c4:ea60In KiriDetach
A device Kiri is waiting for. It isn't on the Mac's bus right now; when it comes back, Kiri attaches it again. Stop waiting leaves it on the Mac instead.

In a terminal, kiri usb ls (or kiri usb list) shows a waited-for device as waiting, and kiri usb detach with its location stops waiting for it:

zsh
$ kiri usb ls
LOCATION     ID         SPEED  STATE      KIND      NAME
0x01100000   10c4:ea60  full   in Kiri    radio     Sonoff Zigbee 3.0 USB Dongle Plus
0x02130000   -          -      waiting    -         ESP32-S3
$ kiri usb detach 0x02130000
Kiri stops waiting for ESP32-S3; it stays on the Mac when it comes back.

Kiri doesn’t keep the Mac awake for a device. For a job that runs unattended, keep the Mac from sleeping, for example with caffeinate -s.

Which device file

Inside the VM, the device gets the name Linux gives it on any PC. Pass that name to --device.

Device In the VM Notes
USB serial adapters (CP210x, CH340/CH341, FTDI, PL2303), many Zigbee and Z-Wave sticks /dev/ttyUSB0 The next one is /dev/ttyUSB1.
Arduino, many ESP32 boards and other CDC ACM devices /dev/ttyACM0
Mice, keyboards and other HID devices /dev/input/event*, /dev/hidraw* Pass the one your program reads, or --device /dev/input.
Anything, for programs that talk to USB directly (libusb) /dev/bus/usb/BBB/DDD Or --device /dev/bus/usb for all of them.

See it in the window

Click a device that’s in Kiri to open its details. In a container gives the line to use, as a docker run flag or as Compose lines, with Copy. Inside Linux lists every file and network interface the device made, and what each one is: a serial port, input events, raw HID, a disk, a network interface, or the raw USB node.

Kiri
Sonoff Zigbee 3.0 Dongle10c4:ea60In Kiri
In a containerdocker runcompose
–device /dev/ttyUSB0Copy
Inside Linux/dev/ttyUSB0serial port
Inside Linux/dev/bus/usb/001/003raw USB
A Zigbee stick's details. The docker run tab gives the --device flag to copy; Inside Linux lists what the stick made in the VM.

The Compose tab gives devices: ["/dev/ttyUSB0:/dev/ttyUSB0"]. A network adapter shows its interface name instead of a device file, and a webcam or audio device shows its files with nothing to copy yet.

Or list what the VM has from a terminal:

zsh
$ docker run --rm --privileged alpine sh -c 'ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null'
/dev/ttyUSB0

On Windows and Linux

Windows. Kiri’s containers run in WSL, and WSL gets USB devices through usbipd-win, the tool Microsoft recommends for it. The USB section in Kiri’s window works the same as on a Mac, with On this PC for a device that is still Windows’. The first time you attach a device, Windows asks an administrator to let usbipd-win share it. If usbipd-win isn’t installed, the section offers to install it. You can also attach from PowerShell with usbipd attach --wsl --busid <BUSID>; see Kiri on Windows.

Linux. Containers run on your computer’s own Linux, so they already see its USB devices: there is nothing to attach. The USB section lists them, with the device file to pass to --device and a button that copies it. kiri usb list shows the same, with each serial device’s tty.

© 2026 Kiri · runkiri.com