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. We mount a tmpfs (RAM disk) and copy persistent state into it, then bind mount it over . NetBird sees a normal writable , but all writes go to RAM.

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 tmpfs is recreated and populated from your saved state.

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 .

Create the persistent state directory:

Now create the setup script at :

Create a systemd service that runs this script early in the boot process, before NetBird starts, and saves state back on stop. Save it at :

Enable it:

Installing NetBird

NetBird is installed from the AUR using . The package provides pre-built binaries with SHA256 checksum verification, avoiding the need to compile from source on the Pi.

Note: must not run as root. PiKVM provides the unprivileged user for this purpose.

Update the system and install build dependencies, then clone and build the AUR package:

The AUR package ships a systemd template unit () whose default configuration 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 a systemd drop-in override to redirect logs, disable SSH config writes, and add a dependency on our overlay service.

Create the override at :

A few things to note about this override:

• 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.
• is first cleared with an empty assignment, then set with the new command. In systemd, is a list-type setting -- an empty assignment clears the previous value so the next line replaces it rather than appending to it.
• is cleared to prevent systemd from trying to create a log directory on the read-only filesystem.
• 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.

Updating NetBird

Since NetBird is installed from the AUR rather than an official repository, updates must be performed manually by rebuilding the package:

Troubleshooting

Service fails with : The service is trying to write logs to a file on the read-only filesystem. Make sure the systemd override includes as described above.

: The tmpfs mount in the overlay script is failing. Check that is writable and that the script is executable ().

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 a similar tmpfs overlay pattern)
• Connect to Your Homelab from Anywhere with a Raspberry Pi