🖥️ NanoKVM OS

Your tiny KVM. More possibilities.

Browser KVM, Internet over USB, remote access and a full Alpine system — on SG2002 NanoKVM hardware.

🚀 Install · ✨ Features · 📦 Releases · 🔌 Hardware · 🔄 Update · 💻 Build · 🧪 Help test · 🐛 Issues

---

✨ What is NanoKVM OS?

NanoKVM OS is independent community firmware for the SG2002-based NanoKVM. Control a computer through HDMI and USB from a desktop or phone, mount installation media, reach a headless Linux console, or give the connected computer Internet through the same USB cable.

Underneath the interface is Alpine Linux 3.24 on a writable F2FS root, with ordinary APK packages, OpenRC services and official Alpine userspace. You can install software, update individual components and retain your settings without rebuilding or reflashing the entire card.

See the latest application release for what’s new, or get the latest SD image for a fresh installation. Applications and images have separate version numbers; package-only updates keep the previous image available.

Important

Help wanted — NanoKVM Cube, Lite and PCIe testers! More real devices make NanoKVM OS better. We need owners to try releases and report what works, as well as what does not. No coding required. Even a short “works on my board” report helps us confirm support and catch regressions. Help test your NanoKVM →

🚀 What you can do

🎬 Video, from HD to 4K

Landscape resolution	Maximum monitor refresh rate
4K / UHD — 3840 × 2160	Up to 30 Hz (H.265)
QHD — 2560 × 1440	Up to 60 Hz
Full HD — 1920 × 1080	Up to 90 Hz
HD — 1280 × 720	Up to 120 Hz

These are the highest advertised monitor timings on an LT6911UXC receiver, not guaranteed delivered video rates. LT6911C and LT6911D receivers offer 720p and 1080p at 60 Hz. Available modes also depend on video memory, source timing, codec and browser. The interface reports the input and encoded stream separately and explains unavailable choices. See video modes and receiver limits.

• H.264 up to 2560 × 1440 and H.265 up to 4K, over Direct or WebRTC, plus MJPEG. New browsers start with the device’s selected transport; existing browser preferences are retained. RustDesk follows the device transport. Viewers share the device’s codec, picture settings and hardware budget.
• Hardware video encoding, automatic/economy/manual bitrate controls, measured bitrate, and Direct playback options for responsiveness or a smoother picture. NormalP keyframes are requested as needed, with a periodic safety interval. Bitrate is an encoder ceiling; actual traffic depends on the image and operating conditions.
• Adaptive MJPEG quality and JPEG colour sampling: quality falls when all viewers lag and recovers up to your selected limit. Choose 4:2:2 (default) or 4:2:0, with the selection saved across reboots. MJPEG and screenshots carry the screen's true colours (full-range JPEG); with 4:2:0 or frame detection, while no H.264/H.265 viewer shares the video output. The monitor profiles let the PC send full-range RGB, so black stays black in every codec.
• Virtual monitor / EDID controls: choose the resolution, refresh and orientation seen by the managed computer independently from the stream-size limit. Resolution and frame rate have separate controls; the monitor timing follows the stream rate where the receiver can be updated live. A resolution that needs another installed video-memory mode offers to switch it and reboot. Cube/Lite EDID changes require a physical power cycle; the interface explains when it is needed. Same as input preserves the input dimensions.
• Portrait profiles: 720 × 1280 and 1080 × 1920 with H.264 or H.265, 1440 × 2560 with H.265 (H.264 only with a stream resolution of 1080p or lower), subject to the reported device and browser capabilities.
• PNG screenshots and browser-side recording, plus USB audio playback in the browser through a shared Opus encoder. Direct and WebRTC record the H.264/H.265 stream into MP4 as received, without re-encoding; MJPEG records WebM. Recordings include the USB audio while it plays in the page. Direct/WebRTC preserve the received Opus packets when encoded receiver access is available (the shared device encoder targets 192 kbit/s); the browser encoding fallback also targets 192 kbit/s. A buffer limit or source interruption saves the captured portion with a warning. The single file is committed when recording finishes; a browser crash can still lose an unfinished recording. Recording availability depends on the browser’s recording and encoded-stream APIs.
• Playback recovery: Direct requests fresh keyframes after dropped frames; stalled capture has a bounded recovery path. H.264/H.265 streams carry BT.709 colour information.
• HDMI enable/disable and capture idle timeout, so capture can stop when no viewer is watching.

H.265 requires a browser and platform with a compatible decoder. Direct playback uses WebCodecs in a secure context. The device does not transcode a shared H.265 stream separately for a browser that only supports H.264. The H.264 encoder corrupts 3840 × 2160 pictures, so 4K needs H.265; with H.264, choose a stream resolution of 1440p or lower. MJPEG and JPEG-based screenshots are unavailable with a 4K HDMI input; concurrent MJPEG and H.264/H.265 viewers share capture resources and can reduce delivered FPS.

📱 Control from a desktop or phone

• A movable, collapsible toolbar and responsive settings with reachable Apply controls.
• Relative mouse and absolute pointer modes, touchpad gestures, scrolling and IME input. Hold one finger and tap with another to right-click.
• One-click keyboard sequences: Ctrl+Alt+Del, Magic SysRq and REISUB, with timing handled by the device.
• Multiple viewers with server-enforced input ownership. Additional sessions start with control locked; control can be transferred explicitly, and the sole remaining viewer receives it automatically when the owner disconnects.
• Controls follow the USB composition: disabled input functions are hidden, and the control lock is shown only when USB input is enabled.
• User accounts with administrator/user roles, administrator-only shared video settings and a Logout action.

Viewers share the device's encoder and video settings. Multiple sessions do not create independent Windows desktops or independent host mouse pointers.

🔌 One USB connection, several jobs

Configure the USB gadget through presets (KVM, with USB network, with the serial console, a headless server, remote desktop, keyboard and mouse only) or individual switches for the keyboard, relative mouse, absolute pointer, network, virtual storage, serial console and audio. The interface checks the controller's endpoint budget before applying a combination and says what each preset gives up. USB can also be disabled entirely. You can also configure the USB device identity (VID, PID and identifying strings).

Function	What it provides
Keyboard and pointers	Browser control, with normal and HID compatibility profiles
Virtual media	SD-backed images or direct ISO mounting from your computer without first copying the ISO to the card; CD/DVD images up to 31.625 GiB
Network boot	Boot the managed computer from the netboot.xyz menus over USB network, with the official iPXE images (UEFI Secure Boot signed one included)
User disk	A writable FAT32 USB drive backed by an image on the SD card, for BIOS update files, profiles and logs; selectable sizes from 64 MiB to 4 GiB; browse folders, upload/download files and manage contents while detached from the computer
USB network	Local access to NanoKVM through the USB NCM adapter
Internet over USB NCM	Share the NanoKVM Ethernet/Wi-Fi uplink with the managed computer
USB Serial / CDC ACM	Reach a configured host serial console through the browser terminal

Internet over USB has its own switch in Settings → USB, off by default. It provides IPv4 DHCP, DNS and NAT, with software flow offload for eligible TCP/UDP connections. Turning sharing off keeps local USB access. Existing VPN routing and firewall policies are respected; conflicting routes can leave sharing waiting for a usable uplink. See USB Internet sharing.

For a headless Linux login, enable USB Serial and set the login up on the managed host with the console helper from the USB settings page: a script that reads the host first, refuses when it cannot work safely, keeps backups and can undo; it also comes on a read-only helper disk for hosts without a network. This works after the host USB stack loads; it does not provide pre-USB BIOS/UEFI output. See USB composition and serial setup.

ATX power/reset controls are available on supported boards. Wake-on-LAN includes a saved list of named MAC addresses for frequently used machines.

🌐 Network and remote access

• Ethernet and Wi-Fi controls, hostname, DNS, gateway, IPv6 and mDNS settings. Ethernet shows live link status and the current address; static IPv4 accepts CIDR notation and an optional gateway for direct computer connections. IPv6 is configurable per interface, with settings retained across reboots.
• 2.4 / 5 GHz Wi-Fi on compatible adapters: automatic scanning across both bands, grouped network entries, signal-strength icons, hidden-network setup and a preferred band. 5 GHz is preferred by default, with fallback to 2.4 GHz. Connection details and a Disconnect action are available in the interface.
• Shared STUN/TURN settings under Network for browser WebRTC video/audio and RustDesk: use the default or custom STUN servers, disable STUN, or configure an authenticated TURN relay.
• Bluetooth controller switch on supported AIC8800 boards, off by default. Enable it under Network without coupling the Bluetooth module to Wi-Fi; this is a controller switch, not a peripheral-pairing interface.
• A single VPN overview for WireGuard, OpenVPN 2, Tailscale and NetBird, with installation state, version and connection/profile controls. OpenVPN, Tailscale and NetBird are optional APK installations.
• WireGuard .conf profiles with an explicit Route Allowed IPs option; OpenVPN routed TUN .ovpn profiles, including referenced certificate/key files in the same upload.
• HTTPS from first boot with a unique device certificate and HTTP redirect. Newly generated certificates use ECDSA P-256; existing certificates are preserved. A custom certificate (your own CA or a public one) can be uploaded in Settings → Network and takes effect for new connections without a restart; a custom pair that cannot be loaded never blocks start-up (the generated one stands in). Let's Encrypt / ZeroSSL / Buypass / Google certificates through acme.sh, installed from its latest release on demand: HTTP-01 on port 80 or DNS-01 with every DNS provider acme.sh ships, renewed from the server and served without a restart. SSH can be enabled from settings.

🧩 Software and add-ons

Software is a top-level settings section. Its package manager searches repositories and installs, removes or updates packages using the same APK database as the terminal. Install tools such as nano, htop, mc or Python as needed.

Daily package-index refresh is optional and off by default. Enable it in Software → Packages and choose a time in the device timezone. It refreshes the available-package lists; it does not automatically install updates. Manage optional software in Software → Add-ons. RustDesk updates are discovered from the signed repository, including for older file-pinned installations.

Add-on	Installation and capabilities
RustDesk	Optional signed APK, managed from Software. Share the captured HDMI display and USB input using the official RustDesk servers or your own; temporary/permanent passwords, H.264/H.265, direct/relay TCP, and WebRTC when it is the video transport. Based on the RustDesk 1.5 protocol.
PicoClaw	Install, update or remove the official latest RISC-V release from Software → Add-ons. Configure the model, API key and endpoint for remote-control or general-assistant use. Its navigation entry appears only while installed.
acme.sh	Install on demand from Software → Add-ons, then configure HTTPS certificates in Settings → Network. Issue and renew certificates through ACME using HTTP-01 or DNS-01 with supported DNS providers; renewed certificates take effect without restarting the service.

RustDesk can forward USB audio; its integration does not include clipboard, file transfer, terminal, chat or ATX control. Its packages and corresponding sources are published independently of OS releases: an installed add-on can be updated without waiting for a new NanoKVM OS version.

PicoClaw is downloaded from its upstream release, not packaged as a NanoKVM APK. An MCP endpoint with enable/disable and API-key controls is also available under System for external AI clients.

⚙️ System controls and everyday tools

Area	Controls and information
Dashboard	CPU load, RAM, SoC temperature, CPU frequency, storage, network, VPN and time-synchronization status
Memory	One reusable 144 MiB video region shared with Linux (every resolution up to 2160p, no reboot); ZRAM with automatic sizing and optional ZSTD recompression; SD swap; a configurable Go runtime soft memory limit, defaulting to a quarter of the memory Linux keeps under 2160p capture
CPU	Frequency control, thermal protection and an explicit Apply at startup option; an incomplete overclocked startup triggers a 1000 MHz fallback on the next boot
Diagnostics	Service, USB, firewall and package-operation status, plus system logs in the GUI
Terminal	Browser shell and serial sessions, with shell command history
Scripts	Shell and Python scripts on the device, run on demand or once per boot, with startup status and bounded logs. Startup scripts survive application service restarts without running twice; Python is installed separately. See Scripts
Appearance	Menu layout/icons, colours, language, web title, bundled branding choices and custom logo/favicon uploads
Device	OLED settings, mouse jiggler, date/time and reboot controls

The interface shares live-status polling, loads settings pages on demand, and serves compressed, cacheable assets. Package operations are serialized and check available memory before starting. OpenRC manages services independently of video initialization.

🔌 Compatible devices

Works with NanoKVM Cube, Lite and PCIe — the SG2002 RISC-V NanoKVM family. The full image selects the board profile automatically.

Device	Included support	Physical validation
✅ NanoKVM Cube	Alpha and serial-production board profiles	Community-tested: serial-production board detection and OLED confirmed on beta13 (#2)
✅ NanoKVM Lite	Base profile, without ATX	Community-tested on v3 after upgrading from v2.5: boot, 1080p60 video and KVM control confirmed (#215)
✅ NanoKVM PCIe	Board profile and receiver detection	PCIe/UXC development bench; LT6911D video confirmed by a community tester on v2.0-b5 (#8)

Incompatible hardware: NanoKVM Pro and NanoKVM USB use different hardware platforms. This firmware cannot run on them; they are not untested variants of the supported models.

Receiver-specific features, including higher resolutions and programmable EDID, vary by board. Included profiles are not a claim of physical qualification on every revision. See board support.

🧪 Help wanted: test on Cube, Lite and PCIe

Hardware testing is one of the most valuable ways to help this project. The development bench cannot cover every board revision, HDMI receiver, computer and browser. Cube and Lite owners are especially welcome; additional PCIe units and receivers are just as useful.

1. Try the current release using the installation or update instructions.
2. Check what you normally use: boot and network access, video and audio, keyboard/mouse, USB media, and OLED or ATX controls where your board has them. A desktop or phone session and reconnecting after a reboot are useful checks. You do not need to test every feature.
3. Share a test report — a successful test is worth reporting too. Include your board/revision, HDMI receiver if known, application and image versions from About, fresh install or upgrade, browser/OS, and the resolution/FPS, codec and transport you tried. Say what worked and what failed; for a failure, add reproduction steps and relevant GUI logs.

Already helping with an issue? Add your results there instead of opening a duplicate. Please remove passwords, tokens and private screen contents from reports. Thank you — each real-device report helps us fix regressions and make the compatibility table more useful.

🚀 Install the latest SD image

The latest SD image page always points to the newest published image. An application-only release does not replace it.

1. Open that page and download the image ZIP and SHA256SUMS from the same image release.
2. Verify the ZIP checksum, extract the .img and flash it to an SD card of at least 2 GB. Flashing replaces the card's existing installation and data.
3. Boot NanoKVM, allow automatic board selection and its restart to finish, then open https://DEVICE-IP/.
4. Sign in with admin / admin and set a new password when prompted. For the administrator, this also sets the Linux root password used by SSH. SSH is disabled by default.
5. Open Settings → System → Updates to install application and system-package updates published since the image was built.

The image uses a 64 MiB boot partition and 768 MiB F2FS root; first boot creates an exFAT data partition in the remaining space. See installation details.

Image and application versions are independent: later APK updates preserve the original image identity. About shows the installed image, its bundled applications and the current application version.

🔄 Update an existing installation

v2.0-a2 or newer: use Settings → System → Updates (on a2: Settings → Updates → Package updates) or run as root:

apk update
apk upgrade
reboot

Release channel: Settings → System → Updates offers Stable (default) and Beta (opt-in previews, which may have regressions). Switching selects where future updates come from; it installs nothing by itself. After returning to Stable, Install stable version restores the current stable firmware even when its packages are older. Confirm the rollback; settings and data are kept, and a kernel or bootloader change requires a reboot. Existing installations stay on Stable. Independent stable add-on releases are available in both channels.

Updates retain settings, user data and independently installed packages. The thirteen core packages include nanokvm (backend), nanokvm-web (UI) and the nanokvm-app compatibility metapackage. Existing installations migrate automatically; later web-only updates need a browser refresh instead of a backend restart. Kernel and bootloader updates need a reboot to take effect. Application service updates use OpenRC automatically; no separate apply command is needed.

• Local .apk installations: file-pinned packages may require an apk add step before upgrading; see update instructions.
• Signing transition: nanokvm-keys installs the public keys and moves the official repository to the RSA/ECDSA-signed v3 index automatically. The RSA-signed legacy index remains available for older installations.
• C906 overlay installations: follow the stock Alpine migration instructions. Updating NanoKVM alone does not remove the overlay.
• Stock firmware, pre-v2 releases or the original v2.0-a1: install the full SD image. Legacy .nkos updates do not migrate the system to Alpine.

The bootloader package updates fip.bin on existing installations; see bootloader updates and recovery. A full image includes the rebuilt bootloader as well as the applications and system packages.

💻 Build from the public repository

The repository contains the application, browser UI, native integration, kernel/driver patches and complete image build. It fetches upstream sources at the revisions and hashes recorded in platform/sources.lock. CI publishes output hashes and compares changed components against the main build. Reproducing outputs requires matching build inputs; moving Alpine repositories and release-archive timestamps can still differ between builds. Separate private SDK checkouts are not required.

For a local test build, after installing the host prerequisites:

git clone https://github.com/dormancygrace/NanoKVM-OS.git
cd NanoKVM-OS
git checkout v3.3.3
platform/build.sh -d

-d generates local test signing keys. Official release builds require the maintainer's RSA and ECDSA keys; test-signed packages are not official updates. See build and signing instructions.

The platform uses Linux 7.3, U-Boot 2026.10, OpenSBI 1.9 and a GCC 16.2 / T-Head C906 toolchain. Kernel/modules use -O3 without LTO; native userspace uses the reviewed scalar -O2 profile. Web builds use Node.js 24 LTS. Most ordinary userspace, including OpenSSL, comes from official Alpine repositories; exfatprogs, i2c-tools and the zlib-compatible zlib-ng library are maintained in NanoKVM packages; the optional C906 package profile is retained for experiments.

Pinned platform inputs, Go modules and the web lockfile fix their respective source versions. Alpine 3.24 repositories continue receiving updates, so later builds can install newer Alpine packages; the build records them in release/installed-packages.txt.

Source directory	Contents
server/, web/	Go application, streaming/API services and React/TypeScript interface
support/	Native media/board integration and device tools (kvm_system, MMF, nanokvm_update_edid)
firmware/	Alpine recipes, OpenRC integration, retained SDK inputs and board support
platform/, scripts/	Pinned platform build, patches, packaging and image generation
tests/	Host-side tests of the init scripts, build, packaging and update tooling

🌍 Translations

The language menu includes 25 languages, with partial translations falling back to English. Hebrew is available as a translation starter. Translations are maintained on Hosted Weblate: anyone can fix or add strings in the browser, without git. See TRANSLATING.md.

🌍 Made welcoming by our translators

Thank you to Pavel Borecki for Czech, Alexander-Ger-Reich for German and English UI maintenance, and polyzium for Russian localization — and to everyone who translates, reviews, and improves the words on screen. See the translation credits and contribution guide.

Hosted Weblate is our community translation platform. Thank you to the Weblate project for the tools and hosting that let people contribute directly from their browser. Help translate NanoKVM OS.

💖 Support development

If NanoKVM OS makes your hardware more useful, consider sponsoring Gleb Pesin on GitHub. Your support helps fund development time and hardware testing. One-time and monthly contributions of any amount are welcome.

Testing, bug reports, translations and code contributions are just as valuable. Thank you for helping improve NanoKVM OS.

💚 Community-funded hardware

Thank you, Pavel Borecki, for generously funding the purchase of a Sipeed NanoKVM Cube! Alongside his Czech translations, Pavel is helping make hands-on Cube development and regression testing possible. This support will help me reproduce Cube-specific issues and verify fixes on real hardware.

📦 Donate hardware

Help improve NanoKVM OS on supported devices and explore new ports! I’m looking for donated hardware:

• Sipeed NanoKVM Cube — 💚 Funded by Pavel Borecki. Thank you for your generous donation!
• Sipeed NanoKVM-GO
• Sipeed NanoKVM Pro (Desk WiFi)
• Sipeed NanoKVM Pro (ATX+WiFi)
• Sipeed NanoKVM-USB

Working used devices and manufacturer development samples are welcome. If you have one to contribute, please email me with the model and hardware revision before shipping so we can arrange delivery to Israel.

Cube is part of the supported SG2002 family. The GO, Pro and USB models above are targets for exploration and cannot use the current image. A donated device helps make development possible, but a new port and its timeline depend on the hardware, documentation and available source code. Progress will be shared openly, and hardware contributors will be credited unless they prefer to remain anonymous.

❤️ Credits and licenses

Built on the work of Sipeed, SOPHGO, Milk-V, Alpine, Linux, Buildroot, Go and Pion, with thanks to the contributors and hardware testers.

Special thanks to iPXE for the network bootloader and official boot images, including UEFI Secure Boot support, and to netboot.xyz for the network boot menus, operating system installers and recovery tools that make our Network boot feature possible.

NanoKVM application changes retain the upstream GPL-3.0 license. Other components retain their own licenses and notices. See third-party notices, distribution status and the corresponding-source build. Release downloads include the corresponding-source archive; RustDesk has its own source release.

When reporting an issue, include the board/HDMI receiver, application version, browser/client, codec and transport, resolution/FPS target and reproduction steps. Remove credentials and private screen contents from logs.