kvm-it
A KVM for the machine that has nothing on it yet.
See it. Type at it. Install it. No software on the target, no network, no hundred-dollar IP-KVM: an ESP32-S3 dev board (~$10), a cheap
HDMI capture card, and one app.
Three steps
- Get the parts. An ESP32-S3 board with two USB-C ports (COM and USB) and a USB HDMI capture card. Details: get started.
- Install the app. Download from Releases: a signed
.msi/.zip for Windows 11, an
.AppImage for Linux. Double-click or chmod +x. That is the whole "dev environment": no Rust, no Docker, no drivers, no DLLs to hunt down.
- Plug in. In the app: Adapter > Flash adapter… (one click; the firmware is inside the app), pair once, and drive.
What you get
- See and drive the target in one window. Click the picture and your keyboard and mouse belong to the target; Ctrl+Alt+Esc gives
them back (that chord is never sent). It works from the BIOS splash onward: if the target takes a USB keyboard, kvm-it can drive it.
- The keys your PC would swallow. One-click Ctrl+Alt+Del, Win, Alt+Tab, PrintScreen and more; on Windows, the rest go to the target too.
- Zero-step reconnect. Pair once. Move the cables to the next machine and the app reconnects by itself.
- Replayable setup scripts. Native TOML or imported DuckyScript: text, keys, chords, delays, and wait-for-the-screen steps, so one slow
install screen does not wreck everything after it. Preview and dry-run before anything is typed; abort leaves nothing held down.
- Boots a bare machine from the network. One click turns on the adapter's read-only USB drive carrying iPXE (off by default): pick it in the target's boot menu and
reach an installer, WinPE or a rescue image (UEFI targets; Secure Boot support is signed but only tested in a virtual machine so far: see the status table).
- Flashes its own adapter, in the app, and keeps the pairing.
- Safe with secrets. Passwords are masked, never logged, never saved. Pairing needs physical presence: plug it in or press its button.
- Open. MIT-licensed; the wire protocol, firmware and every review round are in this repo.
The target needs no software, drivers, network or Bluetooth.
Target HDMI out ──► USB capture card ──► your PC ──► kvm-it (live video)
Your keyboard/mouse ──► kvm-it ──► Bluetooth LE ──► ESP32-S3 ──► USB HID ──► target PC
Everything the app does is also on the command line:
kvmit scan | status | type "text" | key ctrl alt delete | run script.toml [--dry-run] | import payload.txt | flash.
Full walkthrough on the docs site or docs/getting-started.md. Read
the hardware guide once: which USB-C port goes where, what the LED and BOOT button mean.
Hacking on it? Building from source (that is where Rust and Docker live): docs/developing.md.
Status: v0.4.8
Labels are strict: built = compiles; host-tested = automated tests pass in CI/containers;
hardware-verified = run on a physical board; VM-verified = run in a Windows 11 virtual machine on a Linux
host with the Bluetooth adapter and the capture card passed through over USB (the real radio and the real card, but
not bare-metal Windows).
| Area | State |
|---|
| Firmware: USB keyboard + mouse (boot HID) | hardware-verified (enumeration via lsusb; self-test typed) |
| Firmware: protocol dispatcher, dedup, keepalive, LED language, BOOT gestures | host-tested |
| Firmware: BLE (bonding, pairing window, GATT), BOOT GPIO | hardware-verified (BOOT opens the window; LE SC bond; HELLO/STATUS over GATT; bonded reconnect) |
| Firmware: LED driver (GPIO48), BOOT gestures | hardware-verified (fast blue while pairing; 10 s BOOT hold: yellow ramp, three red flashes, fast blue, bond erased) |
| Protocol v1 spec + shared vectors (C and Rust) | host-tested |
| Desktop: client (ack/retry/keepalive), script engine, DuckyScript import, layout | host-tested |
| Desktop: BLE transport + BlueZ pairing | hardware-verified on Linux/BlueZ (Intel AX201): scan, pair, status (90 ms RTT); type/key hardware-verified into a Windows 11 target (every printable US-ASCII character, checked on screen through the capture card) |
Desktop: BLE on Windows (WinRT pairing, scan, status, unpair, faster-connection request) | VM-verified: pairing with no system dialog, status (30 ms RTT with the fast connection, 120 ms without), key --hold; sustained mouse motion at 60 and 125 frames/s no longer collapses the link. kvmit type was not run from Windows. Bare-metal Windows: not tested |
| Desktop: V4L2 capture | hardware-verified with an HDMI capture card (MacroSilicon 345f:2109): 1920x1080 frame of a live Windows 11 desktop via kvmit video snap |
| Desktop: Media Foundation capture (Windows) | VM-verified with the same MacroSilicon card: video list, a 1920x1080 MJPEG video snap, live video in the GUI, and a notice (not a frozen frame) when the card is unplugged mid-stream. The YUY2 path is untested |
| Desktop: egui GUI, v0.1.0 layout (left panel) | maintainer-checked on Linux with an adapter and a target (2026-10-03), including the input-ownership changes |
Security note
kvm-it types credentials into other machines. Secrets are never logged and never persisted by default.
Read docs/security.md before using it for anything you care about.
Repository
| Path | Purpose |
|---|
firmware/ | ESP-IDF project (ESP32-S3, TinyUSB HID, NimBLE) |
protocol/ | Wire protocol v1 and generated golden vectors |
desktop/ | Rust workspace: kvmit app (CLI + GUI) and its library crates |
docs/ | The docs site source: UX and scripting, architecture, hardware, security, roadmap, review log |
scripts/ | Containerised build, test and flash helpers |
License
MIT. See LICENSE.
