From 43c99ec1627a346056b4e97cd33335520e5557a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dav=C3=AD=C3=B0=20Steinn=20Geirsson?= <david@dsg.is>
Date: Tue, 17 Mar 2026 13:10:54 +0000
Subject: [PATCH] Document USB device passthrough in README and CLAUDE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CLAUDE.md |  1 +
 README.md | 34 +++++++++++++++++++++++++++++++++-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 9edd133..6b05dad 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -91,6 +91,7 @@ The configured user can manage VM services via polkit (no sudo required for `vm-
 - `vm-stop <name>` — stop VM via systemd (polkit, no sudo)
 - `vm-start-debug <name>` — start VM directly for debugging (requires sudo)
 - `vm-shell <name>` — connect to VM serial console (default) or SSH with `--ssh`
+- `vmsilo-usb [attach|detach] [<name> <vid:pid|devpath>]` — list USB devices, attach/detach USB devices to VMs
 
 See README.md for full usage details and options.
 
diff --git a/README.md b/README.md
index 75b8b17..1ffe3c0 100644
--- a/README.md
+++ b/README.md
@@ -186,6 +186,7 @@ There are a lot of configuration options but you don't really need to touch most
 | `sound.capture` | bool | `false` | Enable sound capture (implies playback) |
 | `sharedDirectories` | attrsOf submodule | `{}` | Shared directories via virtiofsd (keys are fs tags, see below) |
 | `pciDevices` | list of attrsets | `[]` | PCI devices to passthrough (path + optional kv pairs) |
+| `usbDevices` | list of attrsets | `[]` | USB devices to passthrough (vendorId, productId, optional serial) |
 | `guestPrograms` | list of packages | `[]` | VM-specific packages |
 | `guestConfig` | NixOS module(s) | `[]` | VM-specific NixOS configuration (module, list of modules, or path) |
 | `vhostUser` | list of attrsets | `[]` | Manual vhost-user devices |
@@ -403,6 +404,37 @@ programs.vmsilo = {
 boot.blacklistedKernelModules = [ "xhci_hcd" ];  # for USB controllers
 ```
 
+### USB Passthrough
+
+USB devices can be hot-attached to running VMs individually, without passing through an entire USB controller via PCI passthrough.
+
+#### Configuration
+
+Use the `usbDevices` per-VM option to declare persistent device assignments. Devices are matched by vendor/product ID, optionally narrowed by serial number. All matching physical devices are attached when the VM starts and detached when it stops.
+
+```nix
+banking = {
+  usbDevices = [
+    { vendorId = "17ef"; productId = "60e0"; }
+    { vendorId = "046d"; productId = "c52b"; serial = "A02019100900"; }
+  ];
+};
+```
+
+#### Runtime CLI
+
+The `vmsilo-usb` command manages USB device assignments at runtime:
+
+```bash
+vmsilo-usb                                  # List all USB devices and which VM they're attached to
+vmsilo-usb attach <vm> <vid:pid|devpath>    # Attach a device (detaches from current VM if needed)
+vmsilo-usb detach <vm> <vid:pid|devpath>    # Detach a device from a VM
+```
+
+Devices can be identified by `vid:pid` (e.g., `17ef:60e0`) or by sysfs devpath (e.g., `1-2.3`).
+
+Persistent devices configured via `usbDevices` are auto-attached at VM start. All USB state is cleaned up when the VM stops.
+
 ### vhost-user Devices
 
 ```nix
@@ -527,7 +559,7 @@ The host provides:
 - Console PTY for serial access (`/run/vmsilo/<name>-console`)
 - VM services run as root for PCI passthrough and sandboxing (crosvm drops privileges)
 - Polkit rules for the configured user to manage VM services without sudo
-- CLI tools: `vm-run`, `vm-start`, `vm-stop`, `vm-start-debug`, `vm-shell`
+- CLI tools: `vm-run`, `vm-start`, `vm-stop`, `vm-start-debug`, `vm-shell`, `vmsilo-usb`
 - Desktop integration with .desktop files for guest applications
 
 ### Tray Integration