dsg/vmsilo
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document USB device passthrough in README and CLAUDE.md

Browse source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Davíð Steinn Geirsson 2026-03-17 13:10:54 +00:00
parent 40f726ffcc
commit 43c99ec162
2 changed files with 34 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

1
CLAUDE.md
View file

@ -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.

34
README.md
View file

@ -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