How to Build a PiKVM Remote Server Agent with OpenClaw on Raspberry Pi

PiKVM turns a Raspberry Pi into a full KVM-over-IP device. Connect it to any server's HDMI output and USB port, and you get real-time video of the screen, keyboard and mouse control, virtual media mounting, and ATX power management, all through a web browser. Video latency sits around 35 to 50 milliseconds at 1080p60, which makes it feel like you're sitting in front of the machine.

The problem is that someone still needs to sit in front of a browser.

KVM-over-IP solves the "I'm not physically near the server" problem. It does not solve the "I was asleep when the server crashed at 3 AM" problem. Most PiKVM tutorials end at hardware setup: connect the cables, flash the OS, open the web interface. That gets you remote access. It does not get you remote monitoring, automated diagnostics, or autonomous recovery.

OpenClaw is an AI agent framework that runs on Raspberry Pi hardware. It orchestrates tasks through cloud-hosted LLMs like Claude, GPT-4, or Gemini while keeping hardware requirements low. The Pi handles scheduling and HTTP requests. The reasoning happens in the cloud.

Pair OpenClaw with PiKVM's REST API, and you get a system where the agent continuously checks server health by capturing screenshots, reading the screen via OCR, sending keyboard commands, and triggering power cycles when needed. The agent can distinguish between a routine update reboot screen and a kernel panic. It can type diagnostic commands into a recovery console. It can capture a screenshot of the error, upload it to a shared workspace for your team, and then attempt a reboot, all before you finish your morning coffee.

The setup works in four steps:

1. Install PiKVM on a Raspberry Pi 4 (connected to your server's HDMI and USB)
2. Install OpenClaw on a second Raspberry Pi
3. Create a server health monitoring skill that polls PiKVM's API
4. Configure KVM actions (screenshot, reboot, keyboard input) as tools the agent can call

The rest of this guide walks through each step.

PiKVM and OpenClaw serve different roles and run different operating systems, which makes a two-Pi architecture the cleanest approach.

The PiKVM device

PiKVM V4 Plus ($385) is the pre-built option. It ships as a fully assembled device with a Raspberry Pi Compute Module 4, HDMI capture, USB keyboard and mouse emulation, ATX control board, and a pre-imaged SD card. Plug it in and it works.

For a DIY build, you need a Raspberry Pi 4, an HDMI-to-CSI bridge board (like the Geekworm KVM-A3 or A4), and a USB OTG cable for HID emulation. The DIY route starts around $100 to $120 depending on whether you already have a Pi. Note that PiKVM does not support the Raspberry Pi 5 because the Pi 5 lacks GPU video encoders needed for hardware H.264 encoding. Stick with a Pi 4 or Compute Module 4 for the KVM device.

PiKVM runs its own specialized OS based on Arch Linux ARM. It is purpose-built for KVM functionality and not designed as a general-purpose Linux distribution. Installing additional software on PiKVM OS is possible but unsupported and can break during firmware updates.

The OpenClaw device

OpenClaw needs standard Raspberry Pi OS (64-bit). A Pi 4 with 4GB RAM works well. A Pi 5 with 8GB is the recommended choice for faster response times. The Pi does not run AI models locally. It sends API calls to cloud providers and orchestrates the responses, so CPU and GPU power matter less than a stable network connection.

Minimum requirements from the official docs: 1GB RAM, 64-bit OS, 500MB free disk space. An SSD connected via USB is recommended over an SD card for reliability in always-on deployments.

Why two Pis instead of one

PiKVM's Arch Linux ARM environment is tuned for low-latency video capture and USB emulation. OpenClaw expects standard Raspberry Pi OS with Node.js. Combining them on one device means running OpenClaw on PiKVM's non-standard OS, which introduces maintenance friction every time PiKVM pushes a firmware update. Two Pis on the same local network communicate over HTTP with negligible latency. The PiKVM device stays focused on hardware I/O, and the OpenClaw device stays focused on reasoning and orchestration.

Total hardware cost for both devices: roughly $200 to $250 for a DIY PiKVM build plus a Pi 5, or $440 to $470 with a PiKVM V4 Plus. Power consumption for both devices combined runs around 10 to 15 watts, costing only a few dollars per year in electricity.

PiKVM exposes a REST API at /api/ that gives programmatic control over every function available in the web interface. This API is what lets the OpenClaw agent interact with your server without opening a browser.

Authentication

PiKVM supports HTTP Basic Auth, per-request headers (X-KVMD-User and X-KVMD-Passwd), and session cookies. For agent-to-API communication, Basic Auth is the simplest approach. All endpoints use HTTPS with a self-signed certificate.

curl -k -u admin:admin https://pikvm-ip/api/atx

The default credentials are admin/admin. Change them before exposing PiKVM to any network beyond your local subnet.

Screenshot capture and OCR

The streamer API captures the current server screen as a JPEG image:

curl -k -u admin:admin \
  'https://pikvm-ip/api/streamer/snapshot?save=1&preview_quality=95' \
  --output screenshot.jpg

This is the foundation of autonomous monitoring. The OpenClaw agent captures a screenshot every few minutes and sends it to the LLM for analysis. The model can read text on screen, identify error dialogs, recognize boot sequences, and flag anything unusual.

PiKVM also includes built-in OCR, which extracts text from the captured screen image. For simple status checks like spotting specific error messages, OCR results are often enough. For visual pattern recognition (identifying a blue screen, a login prompt, or a hung GUI), sending the screenshot directly to a vision-capable LLM gives better results.

ATX power control

The ATX API controls physical power states through relays connected to the server's front-panel header:

### Check current power state
curl -k -u admin:admin https://pikvm-ip/api/atx

### Short press power button (ACPI shutdown signal)
curl -k -X POST -u admin:admin \
  'https://pikvm-ip/api/atx/click?button=power'

### Long press power button (forced shutdown)
curl -k -X POST -u admin:admin \
  'https://pikvm-ip/api/atx/click?button=power_long'

### Press the reset button
curl -k -X POST -u admin:admin \
  'https://pikvm-ip/api/atx/click?button=reset'

The distinction between a short press and a long press matters. A short press sends an ACPI shutdown signal, giving the OS a chance to close files and stop services gracefully. A long press forces an immediate power cut. An intelligent agent should always try the gentle approach first.

Keyboard and mouse input

The HID API sends keystrokes and mouse movements to the server as if they were coming from a physical keyboard and mouse:

### Type text into the server console
curl -k -X POST -u admin:admin \
  -d "systemctl status nginx" \
  'https://pikvm-ip/api/hid/print?keymap=en-us'

### Send Ctrl+Alt+Delete
curl -k -X POST -u admin:admin \
  'https://pikvm-ip/api/hid/events/send_shortcut?keys=ControlLeft,AltLeft,Delete'

This enables recovery scenarios that go beyond power cycling. If a server is responsive but a service has crashed, the agent can type diagnostic commands into the console via PiKVM's keyboard emulation, read the output via screenshot, and fix the issue without a reboot.

With PiKVM handling the hardware interface and OpenClaw handling the reasoning, the integration point is HTTP. The OpenClaw agent runs skills, structured tasks that can make HTTP requests, process results, and decide what to do next.

Installing OpenClaw

On the second Raspberry Pi, start with a fresh Raspberry Pi OS Lite (64-bit) installation. The OpenClaw installation process handles dependencies and setup, and the onboarding wizard configures your LLM provider (Anthropic, OpenAI, or Google) and sets up the agent daemon to run at boot. Refer to the official Raspberry Pi installation guide for current setup steps.

OpenClaw stores its state under ~/.openclaw/ and persists across reboots. The daemon process handles skill scheduling and execution while the Pi otherwise sits idle, keeping CPU and memory usage minimal between checks.

Designing the monitoring skill

The core workflow is a loop that runs on a schedule:

1. Call PiKVM's screenshot API to capture the current server screen
2. Send the screenshot to the LLM with context about what "normal" and "abnormal" look like for this server
3. Based on the LLM's assessment, decide whether to take action
4. If action is needed, call the appropriate PiKVM API endpoint
5. Log the result and any screenshots captured during the process

The skill does not need to parse specific UI elements or regex-match log output. The LLM handles visual comprehension. You describe what "healthy" looks like (a login prompt, a running desktop, specific application output) and what "trouble" looks like (a crash screen, an error dialog, a frozen display), and the model figures out which category the current screenshot falls into.

Mapping PiKVM actions as agent tools

The OpenClaw agent needs to know how to reach PiKVM and what actions are available. The key actions map directly to PiKVM API endpoints:

• check_power: GET /api/atx to determine if the server is on
• capture_screen: GET /api/streamer/snapshot to grab a screenshot
• soft_reboot: POST /api/atx/click?button=power for an ACPI shutdown
• hard_reboot: POST /api/atx/click?button=reset for an immediate hardware reset
• type_command: POST /api/hid/print to enter text on the server console
• send_keys: POST /api/hid/events/send_shortcut to press key combinations

Each action is a straightforward HTTP request. The intelligence comes from the agent deciding which action to take and when. A frozen GUI might warrant a soft reboot attempt. A kernel panic screen might justify a hard reset. A login prompt on a server that should be running a headless service might mean the service crashed and the agent should type a restart command instead of rebooting the whole machine.

Store Server Diagnostics Where Your Team Can Find Them

Upload PiKVM screenshots, incident logs, and agent reports to a shared workspace with built-in AI search. generous storage, no credit card required.

Start 14-Day Trial

The value of combining PiKVM with an AI agent becomes clear when you look at specific failure scenarios that the agent can handle without waking a human.

Unresponsive server with a frozen screen

The monitoring skill captures a screenshot and the LLM recognizes that the screen content has not changed across several consecutive checks. The agent then tries an escalating sequence:

1. Send Ctrl+Alt+Delete via the keyboard API to request a graceful restart
2. Wait 30 seconds and capture another screenshot to check if anything changed
3. If the screen is still frozen, press the power button (short press) for an ACPI shutdown
4. Wait 60 seconds and check the power state via the ATX API
5. If the server is still powered on, use the reset button for a hard reset
6. Capture a screenshot of the boot sequence to confirm the server is restarting

At each step, the agent captures and stores the screenshot. If the server comes back up successfully, these screenshots become a post-incident timeline. If it does not recover, they become diagnostic evidence for the human who investigates next.

Kernel panic or blue screen

A vision-capable LLM can recognize a Linux kernel panic or a Windows blue screen in a screenshot. When the agent identifies one, it captures a high-resolution screenshot of the error output (the stack trace on Linux, the stop code on Windows), stores it for later analysis, and then initiates a hard reset because ACPI shutdown will not work when the kernel has crashed.

After the reboot, the agent watches the boot sequence through periodic screenshots. If the server boots normally and reaches its expected state, the agent logs the incident as resolved. If the server fails to boot or crashes again, the agent escalates to a human notification with the full screenshot history attached.

Boot failure and BIOS access

PiKVM's keyboard emulation works at the hardware level, which means it functions during BIOS/UEFI before the operating system loads. If a server is stuck in a boot loop, the agent can press the appropriate key during POST to enter BIOS setup (typically Del, F2, or F12), then navigate menus using arrow keys and Enter via the keyboard API.

This level of intervention requires careful setup. The agent needs context about what the BIOS looks like for this specific server hardware, what keys to press, and what the expected screens look like. You provide this context as part of the skill configuration: what BIOS vendor the server uses, which key enters setup, and where the boot order menu lives.

Rate limiting and cost control

Each screenshot analysis requires an LLM API call. At one check every 5 minutes, that amounts to 288 calls per day. With current cloud API pricing, this runs between $1 and $5 per day depending on the model and whether you send the screenshot as an image or just the OCR text. Sending OCR text instead of raw images reduces costs while still catching most text-based errors. Reserve image-based analysis for less frequent deep checks (every 30 minutes) or when OCR results look ambiguous.

An autonomous agent that fixes problems is only useful if humans can see what it did and why.

Structured incident logs

Every time the monitoring skill runs, it should log the result: timestamp, screenshot filename, LLM assessment (normal, warning, or critical), action taken, and outcome. During normal operation, these logs confirm the system is being watched. During incidents, they become a timeline that shows exactly when the problem started, what the agent saw, what it tried, and what worked.

Store logs locally on the Pi's SSD as a first layer. For team access and longer retention, push logs and screenshots to a cloud workspace. Fastio provides a free tier with 50GB storage, included credits, and no credit card required. The agent can upload incident reports, screenshot histories, and diagnostic captures to a shared workspace. Enable Intelligence Mode on the workspace and your team can search through logs by meaning, asking "show me all kernel panics from the past month" through the Fastio MCP server instead of grepping through files on the Pi.

You could also use local storage alternatives like a NAS, an S3 bucket, or a self-hosted Nextcloud instance. The advantage of a workspace platform is that it combines storage with search, access control, and sharing, so your on-call engineer gets a single link instead of SSH credentials.

Alert routing

Not every finding deserves a notification. A normal health check result gets logged silently. A warning (screen unchanged for 15 minutes, suspicious process output) gets posted to a team channel. A critical finding (kernel panic, failed boot, server powered off unexpectedly) gets an immediate notification via Telegram, webhook, or SMS.

The agent's assessment should include reasoning, not just a status code. Instead of "SERVER DOWN," the alert says "Server at 10.0.1.15 displayed a kernel panic at 03:42. Call trace references a null pointer dereference in the network driver. Screenshot and diagnostic logs uploaded to the incident workspace. Hard reset initiated, server rebooted successfully at 03:44. Monitoring for recurrence."

Handoff to humans

When the agent encounters something it cannot resolve, clean handoff matters. Upload all relevant screenshots, logs, and the agent's assessment to a shared workspace. The engineer who picks up the incident opens a single link and sees the full context, the screenshot timeline, the agent's reasoning at each step, and the current server state, instead of piecing together information from scattered alerts and log files.