NanoKVM Server

August 20, 2026 · View on GitHub

This is the backend server implementation for NanoKVM.

For detailed documentation, please visit our Wiki.

Structure

server
├── common       // Common utility components
├── config       // Server configuration
├── dl_lib       // Shared object libraries
├── include      // Header files for shared objects
├── logger       // Logging system
├── middleware   // Server middleware components
├── proto        // API request/response definitions
├── router       // API route handlers
├── service      // Core service implementations
├── utils        // Utility functions
└── main.go

Configuration

The configuration file path is /etc/kvm/server.yaml.

# Network Settings
proto: http            # Access protocol. Can be changed to `https` only when certificates are configured. Default is `http`
host: ""               # The listening address for the HTTP/HTTPS service. If left empty, all network interfaces will be bound
port:
    http: 80           # The listening port for the HTTP service. Default is `80`
    https: 443         # The listening port for the HTTPS service (effective when HTTPS is enabled). Default is `443`
cert:
    crt: server.crt    # The path to the public key certificate for HTTPS
    key: server.key    # The path to the private key file for HTTPS


# Logging Configuration
logger:
    level: info     # Global log output level. Evaluated options from highest to lowest detail: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`. Default is `info`
    file: stdout    # Log output destination. `stdout` outputs to the standard console. A file path directs log output to that file. Default is `stdout`


# Authentication & Security
authentication: enable              # Whether to enable identity verification for HTTP API and Web endpoints. Options are `enable` or `disable`. Default is `enable`. Highly recommended to leave this enabled for internet-facing devices!
jwt:
   secretKey: ""                    # The secret key used to sign and verify JWT Tokens. If left empty, a random key will be generated automatically on startup
   refreshTokenDuration: 2678400    # The token refresh duration threshold in seconds before forcing a re-login. Default is `2678400` (~31 days)
   revokeTokensOnLogout: true       # Whether logout invalidates all sessions belonging to that user. Other users are never logged out. Setting this to false only clears the browser cookie and is not recommended. Default is `true`
security:
   loginLockoutDuration: 0,         # The duration (in seconds) to ban an IP from attempting to log in again after reaching the failure limit. If set to `0` or left empty, brute-force protection is disabled. Default is `0`
   loginMaxFailures:     5,         # The maximum number of continuous failed login attempts allowed per IP before triggering protection. Default is `5`


# WebRTC Traversal Settings
stun: stun.l.google.com:19302 # The default STUN server address used for NAT hole-punching to establish P2P streams
turn:
    turnAddr: example_addr    # The relay (TURN) server address (format `ip:port`) used as a fallback when P2P connection fails. Leave empty to disable TURN relay
    turnUser: example_user    # The username required for authorization to the TURN server
    turnCred: example_cred    # The credential/password required for authorization to the TURN server

Web Users

NanoKVM uses two device-wide roles:

  • admin: KVM access plus user, system, network, update, storage, terminal, script, MCP, and PicoClaw administration.
  • user: KVM video, keyboard, mouse, paste, power/reset, and Wake-on-LAN access.

Administrators manage accounts from Settings > Account. Account data remains in /etc/kvm/pwd; the server migrates the legacy single-account JSON format in place and writes the multi-user format atomically with mode 0600. Keeping the same path preserves the physical BOOT-button password reset behavior. Users must confirm their current password when changing it themselves; administrators can reset non-owner users from the account manager. Only the device owner can change the device owner's password, because that password is also synchronized to the Linux root account.

All authenticated sessions are backed by the current account state. Disabling, deleting, changing the role or password of a user invalidates that user's HTTP and real-time connections without affecting other users. Multiple users may watch and control the KVM concurrently; input uses the existing cooperative HID coordinator, so simultaneous input can interleave. Video mode, quality, resolution, and MJPEG frame-detection controls remain shared KVM operations; when several users adjust them concurrently, the latest change applies device-wide.

Compile & Deploy

Note: The manual steps below require a Linux x86-64 host with Go 1.25 or newer; they are not compatible with ARM, Windows or macOS. With Docker you can skip them entirely and use the containerized flow instead — the root Makefile (make shell) or the dev container (see "Development" in the root README) — which works on any host OS; run server/build.sh inside the container for a release-equivalent build.

  1. Install the Toolchain

    1. Download the toolchain from the following link: Download Link.
    2. Extract the file and add the host-tools/gcc/riscv64-linux-musl-x86_64/bin directory to your PATH environment variable.
    3. Run riscv64-unknown-linux-musl-gcc -v. If there is version information in the output, the installation is successful.

  2. Compile the Project

    1. Run cd server from the project root directory.
    2. Run go mod tidy to install Go dependencies.
    3. (Optional) If you compiled libkvm.so yourself, you need to modify its RPATH by patchelf --add-rpath \$ORIGIN ./dl_lib/libkvm.so.
    4. Run 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 to compile the project.
    5. After compilation, an executable file named NanoKVM-Server will be generated.

  3. Modify RPATH

    1. Run sudo apt install patchelf or pip install patchelf to install patchelf.
    2. Run patchelf --version. Ensure the version is 0.14 or higher`.
    3. Run patchelf --add-rpath \$ORIGIN/dl_lib NanoKVM-Server to modify the RPATH of the executable file.

  4. Deploy the Application

    1. File uploads requires SSH. Please enable it in the Web Settings: Settings > SSH;
    2. Replace the original file in the NanoKVM /kvmapp/server/ directory with the newly compiled NanoKVM-Server.
    3. Restart the service on NanoKVM by executing /etc/init.d/S95nanokvm restart.

Manually Update

File uploads requires SSH. Please enable it in the Web Settings: Settings > SSH;

  1. Download the latest application from GitHub;
  2. Unzip the downloaded file and rename the unzipped folder to kvmapp;
  3. Back up the existing /kvmapp directory on your NanoKVM, then replace it with the new kvmapp folder;
  4. Run /etc/init.d/S95nanokvm restart on your NanoKVM to restart the service.