PiKVM Control

Use this skill when the user wants to interact with a PiKVM-managed machine or PiKVM hardware.

What this skill covers

• - Authentication against PiKVM HTTP API
• Device info and health checks
• ATX power state and button actions
• HID typing, key presses, shortcuts, and mouse actions
• Streamer status, screenshots, and OCR
• Mass Storage Device (virtual media) status and image handling
• PiKVM Switch active-port and port-level ATX control

Read references/api-reference.md for endpoint details and parameter notes.

Safety rules

Treat these actions as high impact and get explicit user approval before performing them unless the user already clearly requested the exact action in the current conversation:

• - Power off, hard power off, or reset
• Clicking ATX power/reset buttons
• Connecting or disconnecting virtual media
• Uploading, removing, or replacing MSD images
• Switching active KVM ports in environments that may affect another machine
• Sending destructive keyboard shortcuts or arbitrary typed commands

For read-only requests, proceed without extra confirmation.

Environment and auth

Prefer these environment variables when running the script:

• - PIKVM_URL — base URL like https://pikvm.local or INLINECODE2
• INLINECODE3
• INLINECODE4
• INLINECODE5 — true or INLINECODE7
• INLINECODE8 — true to use HTTP Basic Auth instead of X-KVMD-User / INLINECODE11

Notes:

• - PiKVM requires authentication for all API calls.
• For single-request auth, PiKVM supports either X-KVMD-User and X-KVMD-Passwd headers, or HTTP Basic Auth.
• If 2FA is enabled, append the current TOTP code directly to the password with no spaces.

Default workflow

1. 1. Validate that PIKVM_URL, PIKVM_USER, and PIKVM_PASS are available.
2. Start with a read-only request such as info, atx-state, streamer-state, msd-state, or switch-state.
3. Summarize the current state before taking action.
4. For write operations, restate the exact action being taken.
5. After any state-changing action, re-read the relevant state endpoint and report the result.

Script

Use scripts/pikvm_api.py.

Common examples:

CODEBLOCK0

When to use which operation

Read-only inspection

• - info → general PiKVM/device metadata
• INLINECODE24 → current power LED/busy state
• INLINECODE25 → stream and capture health
• INLINECODE26 → mounted image and storage availability
• INLINECODE27 → PiKVM Switch overview

Input control

• - hid-print for plain text entry
• INLINECODE29 for combinations like Ctrl+Alt+Delete
• INLINECODE30 for a single key press
• INLINECODE31 / mouse-move for pointer actions

Screen capture

• - snapshot to save a JPEG locally
• INLINECODE34 to extract visible text from the host screen
• Use OCR bounding box flags when only part of the screen matters

Power and media

• - atx-power for requested state changes (on, off, off_hard, reset_hard)
• INLINECODE40 to emulate case buttons
• INLINECODE41 to choose image and drive flags
• INLINECODE42 to attach or detach the virtual drive from the host

Switch environments

• - switch-active to select a target port
• INLINECODE44 for port-specific power control

Reporting style

When using this skill in an agent workflow:

• - State the PiKVM host being targeted.
• State whether SSL verification is enabled.
• For each action, show the endpoint-level intent in plain English.
• After changes, include the returned PiKVM state that matters most.
• Do not expose passwords, TOTP values, or session cookies.