Skip to content

PiKVM Setup

How to connect a PiKVM device to KVM Fleet.

Prerequisites

  • PiKVM v2, v3, or v4 running PiKVM OS
  • SSH access to the device
  • An enrollment token from the dashboard

Install the agent

PiKVM's root filesystem is read-only by default. The install script handles this automatically, but if you're installing manually:

# Make filesystem writable
rw

# Install
curl -sSL https://app.kvmfleet.io/install | sh -s -- --token <your-token>

# Make filesystem read-only again
ro

The agent installs to /usr/local/bin/kvmfleet-agent and state is stored in /var/lib/kvmfleet/.

PiKVM OS updates

When updating PiKVM OS with pacman, the agent binary and systemd unit persist. However, a full reflash will require reinstalling the agent.

Tip

After a PiKVM OS update, verify the agent is running: systemctl status kvmfleet-agent

Console access

KVM Fleet proxies the PiKVM web UI through the agent's outbound tunnel. The full KVM interface (video, keyboard, mouse, ATX controls, mass storage) is available in the browser — no port forwarding needed.

Network considerations

The agent only makes outbound connections to app.kvmfleet.io on port 443. No inbound ports need to be opened. If your PiKVM is behind a corporate firewall, ensure outbound HTTPS is allowed.

Troubleshooting

Symptom Fix
Agent won't start Check journalctl -u kvmfleet-agent -f for errors
Device shows offline Verify network connectivity: curl -I https://app.kvmfleet.io
Console won't load Ensure kvmd is running: systemctl status kvmd
Agent lost after OS update Reinstall: the enrollment token is single-use, but the state file persists so the agent will re-register automatically