Rust-only IP-KVM for Sipeed NanoKVM with MCP server for AI-driven remote machine control
  • TypeScript 28.3%
  • C++ 23.1%
  • Rust 18.6%
  • C 13%
  • Go 8%
  • Other 9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-19 00:05:39 -05:00
.cargo Ultra fast Rust Video Feed 2026-08-06 16:00:29 -04:00
.github/workflows Wire protected auth routes and preserve credential failures (#1) 2026-10-12 16:44:49 +09:00
crates fix(vision,web): reject non-console frames and high-MSE glyphs in screen OCR 2026-11-19 00:05:39 -05:00
docker feat: Add Rust workspace structure with all core crates and infrastructure 2026-04-09 20:14:56 +00:00
kvmapp Add default mask for static IP 2026-03-27 10:50:18 +08:00
scripts feat: Add Rust workspace structure with all core crates and infrastructure 2026-04-09 20:14:56 +00:00
server docs: update README documentation for RustyNanoKVM 2026-08-06 16:06:58 -04:00
support Fix the issue of occasional IP not displaying 2026-03-26 18:21:47 +08:00
tests feat(triad): RustyNanoKVM 3-AlexiAI + st AST verified triad_rustynanokvm_zero_float_step (v0-4-1771) — What did AlexiAI-Gamma say after merging the PR with zero floats? 'Look Ma, no decimals — just pure rational LOVE!' <3 <3 2026-10-27 05:38:53 +01:00
tools Add webpage logo generation tool and method 2026-03-04 17:09:52 +08:00
web Merge branch 'agent/fix-screen-ocr-20261116' 2026-11-19 00:05:39 -05:00
.dockerignore add: add build system design for human friendly 2025-08-26 03:40:51 +08:00
.gitignore feat: Add Rust workspace structure with all core crates and infrastructure 2026-04-09 20:14:56 +00:00
Cargo.toml Ultra fast Rust Video Feed 2026-08-06 16:00:29 -04:00
CHANGELOG.md release: nanokvm@2.3.6 2026-03-12 16:02:18 +08:00
LICENSE Refactor and clean up code across multiple modules 2026-04-23 03:17:33 -04:00
Makefile feat: Add Rust workspace structure with all core crates and infrastructure 2026-04-09 20:14:56 +00:00
README.md docs: update README documentation for RustyNanoKVM 2026-08-06 16:06:58 -04:00
rust-toolchain.toml feat: Add Rust workspace structure with all core crates and infrastructure 2026-04-09 20:14:56 +00:00

🦀 RustyNanoKVM

Rust License: MIT Platform

A high-performance, lightweight pure Rust rewrite of the NanoKVM IP-KVM software stack for RISC-V devices (Sipeed LicheeRV Nano / SG2002).

RustyNanoKVM replaces the heavy legacy daemon stack with a modular, memory-efficient Rust server (~2 MB binary) that interfaces directly with the Sophgo multimedia ISP driver for hardware-accelerated 1080p video capture, low-latency MJPEG streaming, USB HID emulation, and board management.


🌟 Key Features

  • ⚡ Hardware-Accelerated Video Capture: Direct FFI integration with the SG2002 video processing subsystem for 1080p@60fps HDMI input capture.
  • 🎥 Real-Time MJPEG & Snapshot Streaming: Standard HTTP multipart (multipart/x-mixed-replace) streaming and single-frame 1080p JPEG snapshots.
  • ⌨️ USB HID Emulation: Full keyboard and relative/absolute mouse control via Linux USB Gadget (/dev/hidg*).
  • 🔌 Board Hardware Control: GPIO, ATX power button toggling, I2C communication, and SSD1306 OLED display management.
  • 🪶 Ultra-Low Memory & CPU Footprint: ~2 MB compiled binary size using pure async Rust (Axum & Tokio), using a fraction of the system resources.

📂 Workspace Architecture

The project is structured as a modular Cargo workspace:

crates/
├── nanokvm-server/   # Main Axum HTTP & WebSocket API server
├── nanokvm-vision/   # Hardware video capture (FFI bindings & MJPEG/H.264 stream logic)
├── nanokvm-hid/      # USB Gadget HID keyboard, mouse, and keycode translation
├── board-support/    # Hardware peripherals (GPIO, ATX power, I2C, OLED display, QR codes)
└── nanokvm-core/     # Configuration loader, errors, and common types

🛠️ Building & Testing

Prerequisites

  • Rust 1.85+ (rustup target add riscv64gc-unknown-linux-musl)
  • Cross-compiler toolchain for RISC-V: riscv64-linux-gnu-gcc

Local Development & Unit Tests

Run workspace unit tests using mock hardware mode:

cargo test --workspace --features mock

Cross-Compiling for NanoKVM (SG2002 RISC-V)

To build the release binary for the target RISC-V hardware:

CC_riscv64gc_unknown_linux_musl=riscv64-linux-gnu-gcc \
cargo build --target riscv64gc-unknown-linux-musl --release

The compiled binary will be generated at: target/riscv64gc-unknown-linux-musl/release/nanokvm-server


🚀 Deployment to NanoKVM Device

  1. Transfer Binary & Web Frontend:

    # Copy the compiled binary
    scp target/riscv64gc-unknown-linux-musl/release/nanokvm-server root@<nanokvm-ip>:/tmp/server/nanokvm-server
    
    # Copy static web assets
    scp -r web root@<nanokvm-ip>:/tmp/server/
    
  2. Run Server on Device:

    ssh root@<nanokvm-ip>
    LD_LIBRARY_PATH=/tmp/server/dl_lib /lib/ld-musl-riscv64v0p7_xthead.so.1 /tmp/server/nanokvm-server
    

📡 API Reference

Endpoint Method Description
/api/stream/mjpeg GET Continuous HTTP MJPEG stream (multipart/x-mixed-replace)
/api/stream/snapshot GET Single 1080p JPEG snapshot image (image/jpeg)
/api/application/info GET System and server metadata
/api/application/version GET Server version
/api/hid/keyboard POST Send keyboard input events
/api/hid/mouse POST Send mouse movement and button events
/api/vm/power/short POST Trigger ATX power button short press
/api/vm/power/long POST Trigger ATX power button long press (force off)
/api/vm/reset POST Trigger ATX reset button press

📜 License

Distributed under the MIT License.