How to Set Up NetBird on PiKVM for Secure Remote KVM Access

What We're Doing and Why

It's a tale as old as time - you're on vacation, and after a long, hard day of vacationing, you settle down with your laptop to stream an episode of that show you're currently obsessed with from your NetBird-equipped media server. Lo-and-behold - your server (that always works flawlessly when you're at home) decides that NOW is the perfect is the time to fail catastrophically and become totally unreachable via SSH. You need some way to reboot the machine, but without SSH access you're stuck. That is, of course, unless you have remote KVM access.

KVM stands for Keyboard Video Mouse. Until fairly recently, remote KVM devices were reserved for expensive enterpise-grade motherboards. Lately, though, we've seen a democratization of the remote KVM scene thanks to projects like PiKVM.

PiKVM is an open source project which, as the name implies, uses the Raspberry Pi platform as a cheap, ubiquitous base. PiKVM gives you KVM-over-IP: full keyboard, video, and mouse control of a remote machine through a web browser. It's incredibly useful for managing headless servers, debugging boot issues, or accessing BIOS settings without being physically present.

The challenge here is accessing PiKVM itself when you're not on the local network, since in this scenario your NetBird routing peer was the fallen media server itself. Luckily, the NetBird client is runs on PiKVM, too, meaning that the little device can join your NetBird encrypted WireGuard mesh, with direct peer-to-peer connections and no exposed ports.

There's one complication: PiKVM runs on a read-only filesystem. This is by design, it protects the SD card from corruption during power loss. But NetBird needs to write authentication state, WireGuard keys, and runtime data to disk. We'll work around this with an overlay filesystem that keeps PiKVM's read-only protections intact while giving NetBird a writable layer backed by RAM.

Building a DIY PiKVM

PiKVM comes in two flavors: pre-built devices (the V4 Mini and V4 Plus) that work out of the box, and a DIY option where you assemble it yourself from off-the-shelf parts. The DIY route is significantly cheaper and is a fun weekend project.

If you already have a PiKVM device set up and running, skip ahead to How the Overlay Works .

What You'll Need

Raspberry Pi board - The recommended choice is a Raspberry Pi 4 (2GB) . There's no benefit to more RAM since PiKVM uses very few resources. The Raspberry Pi Zero 2 W also works as a compact, cheaper option, but it lacks wired Ethernet which makes it less reliable for a device you need to depend on.

Note: The Raspberry Pi 5 is not supported. It lacks the GPU video encoders that PiKVM relies on for hardware-accelerated video capture, so it won't give any performance benefit for this use case.

Video capture device - This is what captures the HDMI output from your target machine. You have two options:

• HDMI-CSI bridge (recommended) - Based on the Toshiba TC358743 chip . Connects to the Pi's CSI camera port. Supports H.264 hardware encoding, automatic resolution detection, and has the lowest latency. This is the preferred option.
• HDMI-USB capture dongle - The cheap dongles you see everywhere on Amazon. They work, but only support MJPEG (heavier on bandwidth), have no resolution detection, higher latency, and some users report compatibility issues with BIOS screens. I'll be taking this route today.

Power supply and USB connectivity - This is where it gets a little tricky. The Pi 4's USB-C port needs to simultaneously receive power and act as a USB device (to emulate a keyboard and mouse for the target machine). You need a USB-C splitter that separates power and data:

• Easiest option: A USB-C power/data splitter module (available from the PiKVM team or third-party sellers), a USB-C to USB-C cable (Pi to splitter), a USB-A to USB-C cable (splitter to target machine), and the official Raspberry Pi USB-C power supply .
• Budget option: A USB-C Y-splitter cable with a USB power blocker on the data leg, plus a USB-A to USB-C cable and any 5V 3A power supply.

MicroSD card - Minimum 32GB, Class 10. This is where PiKVM OS lives.

HDMI cable - To connect your target machine's HDMI output to the capture device.

Ethernet cable - To connect the Pi to your network. You can use Wi-Fi on the Pi Zero 2 W, but wired is strongly recommended for a device you want to be reliably reachable.

Flashing the PiKVM OS Image

PiKVM runs its own Linux distribution (based on Arch Linux ARM), not standard Raspberry Pi OS.

1. Download the correct image for your hardware from files.pikvm.org/images . For the most common setup (Raspberry Pi 4 + HDMI-CSI bridge), grab:

   • PiKVM V2 for Raspberry Pi 4 with HDMI-CSI bridge

2. Download and install balenaEtcher

3. Open balenaEtcher, click Flash from file and select the downloaded file (no need to decompress it first)

4. Click Select target and choose your microSD card

5. Click Flash and wait for it to complete

6. Once flashing is complete, insert the microSD card into your Pi, connect the hardware (HDMI capture, USB splitter, Ethernet), and power it on

First Boot and Initial Access

The first boot takes a couple of minutes. Once it's up, you can access PiKVM by navigating to or in your browser. The default credentials are:

• Web UI: username , password
• SSH/console: username , password

Important: Change the default passwords immediately. SSH in and run .

Once logged in, you should be presented with options for accessing the KVM feed and an in-browser terminal session. Confirm that the KVM works as expected (video feed, mouse/keyboard control).

Congratulations, you've successfully built yourself a DIY PiKVM!

For detailed hardware assembly instructions, wiring diagrams, and advanced configuration, see the official PiKVM DIY V2 guide .

How the Overlay Works

Before jumping into commands, it's worth understanding the approach. An overlay filesystem layers a writable tmpfs (RAM disk) on top of a read-only persistent directory. NetBird sees a normal writable , but writes go to RAM while reads fall through to the persistent copy on disk.

The persistent copy lives at . After initial setup or any configuration change, you manually copy the runtime state back to this persistent directory. On the next reboot, the overlay rebuilds with your saved state as the base layer.

Prerequisites

• A PiKVM device (pre-built or DIY, see above) connected to your local network
• SSH access to your PiKVM (default user: , default password: )
• A NetBird account (free for personal use)

Setting Up the Overlay Filesystem

SSH into your PiKVM and switch to read-write mode. All filesystem modifications in this guide require read-write mode, which you enable with and disable with .

First, ensure the kernel module loads automatically on boot:

Create the persistent state directory that will serve as the overlay's base layer:

Now create the setup script at :

Create a systemd service that runs this script early in the boot process, before NetBird starts. Save it at :

Enable it:

Installing NetBird

Install the NetBird client:

The install script creates a default systemd service file that won't work on PiKVM's read-only filesystem. It tries to write logs to and SSH config to , both of which are read-only. We need to edit the service file to redirect logs to the systemd journal and add a dependency on our overlay service.

Edit the service file:

Replace the contents with:

A few things to note about this file:

• and reference so the writable overlay is mounted before NetBird starts.
• sends logs to the systemd journal instead of a file on the read-only filesystem.
• and are set to for the same reason. The empty lines before each (, ) are intentional. In systemd, these directives are list-type settings. An empty assignment clears the previous value so the next line replaces it rather than appending to it. The same applies to .
• prevents NetBird from writing an SSH convenience config to . Without this, you'd see errors in the logs. SSH over NetBird still works fine using IP addresses directly; this only disables the ability to by hostname.

Enable and start both services:

Registering Your PiKVM

There are two ways to register your PiKVM with NetBird. Both use the flag, which prevents NetBird from trying to modify on the read-only filesystem. Assuming you don't need NetBird to resolve custom DNS names for your network's domains, this is the simplest approach for PiKVM.

Option 1: Setup Key (Recommended)

Setup keys let you register without any browser interaction, which is ideal for headless devices.

1. In the NetBird dashboard , go to Setup Keys and create a new key
2. On PiKVM, run:

Option 2: Interactive SSO Login

The browser-based SSO flow also works, but you'll need to complete it on a different device.

On PiKVM, run:

NetBird prints an activation URL:

Copy that URL and open it in a browser on your computer or phone. Complete the login, and the PiKVM terminal will proceed automatically once authentication is confirmed.

Verify and Persist

Check that everything is connected:

You should see and a NetBird IP address like .

Now comes the critical step. Because the overlay writes to RAM, your authentication state will be lost on reboot unless you persist it:

Reboot to verify everything starts automatically:

After the reboot, SSH back in and run to confirm it reconnected without requiring re-authentication.

Important: Any time NetBird writes new state (re-authentication, key rotation, configuration changes), that state lives only in RAM until you persist it. Get in the habit of running the command above after any changes. If you forget and reboot, you'll need to re-authenticate.

Accessing PiKVM Remotely

Once your PiKVM is connected to your NetBird network, you can access it from any device that's also running NetBird:

1. Install NetBird on your laptop, phone, or any device you want to connect from
2. Find your PiKVM's NetBird IP in the dashboard under Peers, or by running on the PiKVM
3. Open in your browser to access the PiKVM web interface

At last, you're free to catch up on The Pitt.

Troubleshooting

Service fails with : The service is trying to write logs to a file on the read-only filesystem. Make sure you edited the service file to use and as described above.

: The kernel module isn't loaded. Check that contains and reboot. You can also load it manually with to test without rebooting.

DNS lookup failures (): If NetBird can't reach , verify that your PiKVM has working DNS:

If this times out, check for a valid nameserver. A stale NetBird daemon process can also cause persistent DNS failures. Restart the service with .

Need to re-authenticate after reboot: You forgot to persist the overlay state. Re-authenticate with (or SSO), then persist:

Related Resources

• NetBird Documentation
• PiKVM Documentation
• NetBird Setup Keys
• PiKVM Tailscale Guide (uses the same overlay pattern)
• Connect to Your Homelab from Anywhere with a Raspberry Pi