Agentic KVM

Agentic-KVM

**FastMCP server giving AI agents bare-metal control of remote machines via PiKVM.**

**Status:** v0.1 foundation. This is the open-source core of a commercial red team appliance and a cloud-hosted computer-use-as-a-service product. It works, it's tested, it's not feature-complete. Contributions welcome.

What it does

Agentic-KVM exposes PiKVM's REST API as MCP tools that any AI agent can call:

• MSD (Mass Storage Device) — Upload ISOs, mount virtual drives, boot from installers
• ATX — Power on, power off, hard reset via motherboard header pins
• HID — Keyboard, mouse, screenshots, and screenshot-based mouse calibration
• Audit trail — Every tool call logged to JSONL for chain-of-custody

Architecture

┌──────────────┐     stdio/MCP      ┌──────────────────┐    HTTPS     ┌─────────┐
│  AI Agent    │◄──────────────────►│  Agentic-KVM     │◄───────────►│  PiKVM  │
│  (Claude,    │                    │  (FastMCP server) │  Tailscale  │  Device │
│   etc.)      │                    │                   │             │         │
└──────────────┘                    └──────────────────┘             └─────────┘
                                           │
                                           ▼
                                    /var/log/pikvm-mcp/
                                    session-.jsonl

The PiKVM client sits behind a `TargetBackend` abstraction. Future backends (Redfish BMC, Azure VM, RDP) will implement the same interface so the tool layer doesn't change.

Quick Start

Prerequisites

• Python 3.12+
• uv for environment management
• A PiKVM device reachable on your network (Tailscale recommended)

Install and run locally

uv sync
export PIKVM_TARGETS='[{"name":"my-kvm","host":"pikvm.ts.net","password":"your-password"}]'
export PIKVM_OPERATOR_ID="your-name"
uv run pikvm-mcp

Docker (recommended for production)

docker build -t pikvm-mc