# NanoKVM: a RISC-V IP-KVM for headless machines, and what its build system expects from you

> NanoKVM is Sipeed's open-source IP-KVM family built on the LicheeRV Nano. It solves out-of-band access to servers and embedded boards, but the hardware tiers differ sharply, and the firmware is built through a Docker toolchain rather than a package manager.

**sipeed/NanoKVM** — Affordable, Multifunctional, Nano RISC-V IP-KVM. It lets you remotely access and control computers as if you were sitting in front of them, making it useful for servers, embedded systems, and other headless machines.

- Repository: https://github.com/sipeed/NanoKVM
- Website: https://wiki.sipeed.com/nanokvm
- Stars: 6,523 · Forks: 332
- Language: TypeScript
- License: GPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/sipeed-nanokvm

## The problem NanoKVM addresses: a machine with no screen and no keyboard

A headless server, an embedded board, or a rack unit in another building has no local console. When the OS fails to boot, when the network stack does not come up, or when you need to change a UEFI setting, SSH is useless because the machine never reaches a state where SSH answers. NanoKVM is an IP-KVM: it sits between the target machine and the network, captures the target's HDMI output, and injects keyboard and mouse events over emulated USB. The README describes the goal plainly: it lets you remotely access and control computers as if you were sitting in front of them. The audience is people running servers, embedded systems, and other headless machines, plus anyone who wants BIOS-level access without a data centre visit.

The product family matters more than the name. NanoKVM-Cube Lite is a barebones kit aimed at DIY users and bulk deployments. NanoKVM-Cube Full adds a case, accessories, and a pre-flashed system SD card. NanoKVM-PCIe is a PCIe-bracket form factor for internal chassis mounting, drawing power from the PCIe slot, with optional Wi-Fi and PoE. NanoKVM-Pro is a separate repository and a different class of device. If you are comparing models, the specification table is the place to start, because the differences are not cosmetic.

## How the capture and control path is put together

The repository is split into layers, and the split tells you where the work happens. The kvmapp directory holds the APP update package, with kvm_system as the core KVM application, kvm_new_app as the trigger for kvm_system updates, jpg_stream as legacy support for direct updates from older versions, plus server and system for integration and essential components. The web directory is the front-end UI, server is the back-end service, and support holds auxiliary modules: the image subsystem, status, updates, OLED, and HID. HID is the emulated keyboard and mouse path; the image subsystem is the capture and encode path.

The back-end is Go, cross-compiled for riscv64. The Makefile sets CGO_ENABLED=1, GOOS=linux, GOARCH=riscv64, and a musl cross-compiler, with CGO_CFLAGS carrying the SG2002 core flags: -mcpu=c906fdv -march=rv64imafdcv0p7xthead -mcmodel=medany -mabi=lp64d. The support modules are built through MaixCDK, activated from /home/build/MaixCDK/bin/activate inside the container, then ./build kvm_system and ./build kvm_system add_to_kvmapp. That add_to_kvmapp step is what folds a freshly built support module into the APP package the device consumes.

The hardware underneath is an SG2002 with a single C906 core at 1.0G, 256M DDR3, and a 32G microSD card on the Cube and PCIe models. Video encoding is MJPEG or H.264, capped at 1080P@60fps. Storage bandwidth on the Cube and PCIe is listed as 32G MicroSD at 12MB/s, against 300MB/s eMMC on the Pro. That number is worth pausing on: the firmware image, the update packages, and any emulated USB ISO you mount all live on that card, and 12MB/s is the ceiling for all of it.

## Installing and building NanoKVM firmware with the Makefile targets

The README points to the wiki for Quick Start and to the releases page for firmware images, and it splits development by subsystem rather than offering one install path. For the system support modules, the build runs in Docker. The Makefile builds a builder image tagged with the host UID and GID so the entrypoint does not have to rewrite the MaixCDK home directory at container start, and it passes the same identity into the container at run time.

Start by listing the available targets. This prints the build system's own description of each target, including check-image, builder-image, shell, app, support, vision, web, release-build, package, release, and clean:

```bash
make help
```

Building the support modules goes through the container, which activates MaixCDK and then runs the sg2002 build script. The target name is support:

```bash
make support
```

The Go back-end is compiled inside the same container with the riscv64 cross-compiler. If you want to run the command directly rather than through a target, this is the exact invocation the Makefile uses:

```bash
cd server && go mod tidy && CGO_ENABLED=1 GOOS=linux GOARCH=riscv64 \
  CC=riscv64-unknown-linux-musl-gcc \
  CGO_CFLAGS="-mcpu=c906fdv -march=rv64imafdcv0p7xthead -mcmodel=medany -mabi=lp64d" \
  go build
```

One environment detail is documented in the Makefile itself: DOCKER_TTY defaults to -it, and the comment notes that allocating a TTY breaks in environments without one, so it can be overridden with DOCKER_TTY=. In CI you would set it empty. The image name can likewise be overridden, which the Makefile says is intended so a prebuilt image such as a GHCR-cached builder in CI can be used instead. For a first real use, the practical sequence is check-image to confirm the builder and show versions, then builder-image if it is missing, then the target for the subsystem you changed. The README does not document rollback for a firmware update, so plan for a spare SD card before you flash a Cube.

## Where NanoKVM is the wrong tool

The specification table draws hard lines. Audio transmit is marked present on the Pro and absent on the Cube and PCIe. HDMI loopout is 4K on the Pro and absent on the Cube and PCIe. If your workflow depends on hearing the target machine, or on daisy-chaining the display through the KVM, the Cube and PCIe are not the device you want, and no firmware update changes that. The Pro also moves from 100Mbps Ethernet to 1Gbps with PoE and Wi-Fi 6, and the README states that hardware-accelerated encoding reduces latency from 100-150ms to 50-100ms. On a Cube or PCIe, 100-150ms is the figure you are working with, which is fine for a console and unpleasant for anything interactive.

Power is a smaller but real constraint. The Cube and PCIe draw 0.2A@5V; the Pro draws 0.6A@5V and can take power over USB-C or PoE. The Cube and PCIe take USB-C only, with PoE listed as optional. If you are mounting a PCIe card in a chassis and expecting the slot to power it, note that PoE is described as optional on the PCIe model, so the exact configuration you order determines what you get.

The security question is the one users ask most often, and it is not settled by the README or the Makefile. Neither says anything about default credentials, authentication hardening, or network exposure. There is a real search phrase about a default password and several about whether the device is safe. Those questions exist because an IP-KVM is, by design, a device that sits on your network with keyboard control over a machine. Treat the wiki as the authority on first-login credentials, and do not expose the web interface to the internet before you have read it.

## NanoKVM against PiKVM and the other RISC-V KVM boards

The comparison is not NanoKVM versus a generic remote-access tool; it is NanoKVM versus other IP-KVM hardware. The specification table places it next to two boards identified as GxxKVM and JxxKVM. GxxKVM runs an RV1126 with four A7 cores at 1.5G, 1G DDR3, 8G eMMC at 120MB/s, 1000M Ethernet, and 4K@30fps or 2K@60fps capture, but it has no serial terminal and no custom scripts, and ATX power control is listed as an extra $15. JxxKVM runs an RV1106 with one A7 at 1.2G, 256M DDR3, 16G eMMC at 60MB/s, 100M Ethernet, 1080P@60fps, one serial channel, no IPMI, and ATX power control as an extra $10.

Against GxxKVM, NanoKVM Cube and PCIe trade capture resolution for two serial channels, custom script support, and ATX power control without an extra charge. Against JxxKVM, NanoKVM adds IPMI and a second serial channel. The Pro sits at the top of the family with 4K@30fps or 2K@60fps, 1Gbps Ethernet with PoE, Wi-Fi 6, 1G LPDDR4X, 32G eMMC at 300MB/s, a 1.47-inch 320x172 LCD, and extras the table lists as sync LED strip and smart assistant.

The README also notes that the Pro's system row reads NanoKVM or PiKVM, which is the one place the documentation acknowledges PiKVM as an alternative software base. That is the substantive difference: PiKVM is a software platform you assemble hardware around, while NanoKVM is a fixed board with a fixed firmware image. You give up hardware flexibility and gain a known-good combination. If you already have a Raspberry Pi and a USB capture dongle, the PiKVM route reuses them; NanoKVM does not.

## Maintenance, licensing, and what an upgrade actually costs

NanoKVM is licensed GPL-3.0. That is a copyleft licence: if you distribute a modified firmware image, the source for your modifications has to be made available under the same terms. Building a private image for your own devices does not trigger distribution, but shipping a modified NanoKVM to a customer does. This is a description of the licence's mechanism, not legal advice; if you are building a product on top of the firmware, get your own counsel.

The repository is not archived, and the last push was on 2026-08-04. The most recent release in the list is 2.5.0, tagged nanokvm@2.5.0 on the same date, following 2.4.3 on 2026-06-09. There is also a v1.4.3 tag dated 2026-06-10, which suggests two parallel version lines rather than one. The README does not explain the relationship between the 2.x and v1.x tags, and that ambiguity is worth resolving before you pick a firmware image.

Upgrade cost is dominated by the build environment, not the source. Every build runs inside a Docker image that carries MaixCDK and a riscv64 musl toolchain, and the first build pulls or produces that image. The Makefile is written to make this tolerable: the image is named after the host UID and GID, and the image name can be overridden to point at a prebuilt builder. The release path is scripts/build-in-container.sh, invoked through the release-build target. What you are maintaining is a cross-compilation container, and when MaixCDK or the toolchain moves, that container is what you rebuild. On the device side, the update mechanism distinguishes kvm_system from kvm_new_app, and jpg_stream exists only for direct updates from older versions, so the upgrade path you take depends on how old the installed firmware is.

## Conclusion

Adopt NanoKVM if you need out-of-band console access to a headless x86 or embedded machine and you are willing to work inside a Docker-based RISC-V build chain; the Cube and PCIe models give you 1080P@60fps, emulated USB keyboard, mouse and ISO, IPMI and Wake-on-LAN. Do not adopt it if you need audio capture or 4K capture, since the README lists audio transmit and HDMI loopout only for NanoKVM-Pro, and the Cube and PCIe units top out at 1080P@60fps with MJPEG and H.264. Before buying or flashing, confirm three things on the wiki: which model you are actually ordering, whether the default credentials have been changed from the factory value, and whether the firmware release you intend to install matches your board revision.

## FAQ

### What is a NanoKVM?

It is a compact, open-source IP-KVM device built on the LicheeRV Nano, a RISC-V board. It captures a target machine's video and injects emulated USB keyboard and mouse input so you can control a headless machine remotely.

### How much power does a NanoKVM consume?

The specification table lists 0.2A@5V for the Cube and PCIe models and 0.6A@5V for the Pro. The Cube and PCIe take power over USB-C, while the Pro supports USB-C or PoE.

### How does NanoKVM compare to other KVM solutions?

The README compares it against two boards listed as GxxKVM and JxxKVM. NanoKVM Cube and PCIe offer two serial channels, custom scripts, and ATX power control at no extra charge, but capture at 1080P@60fps where GxxKVM reaches 4K@30fps or 2K@60fps.

### Is NanoKVM open source?

Yes. The repository is licensed GPL-3.0, and the README points to hardware details and firmware releases alongside the source. The GPL-3.0 terms apply if you distribute a modified firmware image.

### Is NanoKVM safe?

The README and Makefile do not document default credentials, authentication, or network exposure, so this cannot be answered from the repository files. The wiki is the place to check first-login credentials before putting the device on a network.

### How do I set up NanoKVM?

The README points to the wiki Quick Start for getting started, and firmware images are published on the releases page. Development builds run in Docker, where make help lists the available targets.

## Sources

- [Official documentation](https://wiki.sipeed.com/nanokvm)
- [Official README](https://github.com/sipeed/NanoKVM#readme)
- [Project repository](https://github.com/sipeed/NanoKVM)
- [Release notes](https://github.com/sipeed/NanoKVM/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sipeed-nanokvm