PiKVM

Control and inspect PiKVM devices over the PiKVM HTTP API. Use when asked to operate a PiKVM, query power or HID status, type text or shortcuts remotely, tak...

Security Scan

The skill's requirements, instructions, and bundled script align with its stated purpose of controlling PiKVM devices and do not request unrelated credentials or suspicious installs.

Purpose & Capability

Name/description, required binaries (python3), required env vars (PIKVM_URL, PIKVM_USER, PIKVM_PASS, PIKVM_VERIFY_SSL, PIKVM_USE_BASIC_AUTH), and the included script all map directly to calling the PiKVM HTTP API. Nothing requested appears unrelated to PiKVM control.

Instruction Scope

SKILL.md confines runtime actions to PiKVM API calls via scripts/pikvm_api.py, recommends starting with read-only endpoints, and explicitly demands confirmation for high-impact actions (power, media, switching). The script only reads local files when performing msd-upload (expected) and only communicates with the configured PiKVM URL. It does not instruct reading unrelated system files or exfiltrating data to third-party endpoints.

Install Mechanism

No install spec is provided and no remote downloads are performed by the skill itself; it's instruction-only with a bundled Python script. This is the lower-risk pattern for skills.

Credentials

Requested environment variables are the expected set for authenticating to PiKVM and controlling SSL/auth behavior. The primary credential (PIKVM_PASS) is appropriate. No unrelated secrets or cloud credentials are requested.

Persistence & Privilege

The skill does not request always:true, does not modify other skills' configs, and has no required config paths. It runs on demand and has typical agent-level privileges for an invocable skill.

Assessment

This skill looks coherent with its purpose, but protect the required environment variables (PIKVM_USER/PIKVM_PASS) as they grant control over the target device. Only point PIKVM_URL at hosts you trust. The script can upload local images (msd-upload) and can instruct the PiKVM to fetch remote images (msd-write_remote) — both are normal for this use but can be high-impact, so confirm destructive actions (power cycles, media changes, port switching) with the user before running. If you want extra assurance, review scripts/pikvm_api.py yourself and ensure Python's requests library is available in the execution environment.

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 https://10.0.0.7
• PIKVM_USER
• PIKVM_PASS
• PIKVM_VERIFY_SSL — true or false
• PIKVM_USE_BASIC_AUTH — true to use HTTP Basic Auth instead of X-KVMD-User / X-KVMD-Passwd

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. 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:

python scripts/pikvm_api.py info
python scripts/pikvm_api.py atx-state
python scripts/pikvm_api.py atx-power --action on
python scripts/pikvm_api.py atx-click --button reset
python scripts/pikvm_api.py hid-print --text "reboot\n" --slow
python scripts/pikvm_api.py hid-shortcut --keys ControlLeft,AltLeft,Delete
python scripts/pikvm_api.py snapshot --save-path /tmp/pikvm.jpg
python scripts/pikvm_api.py ocr --langs eng
python scripts/pikvm_api.py msd-state
python scripts/pikvm_api.py msd-set --image debian.iso --cdrom true --rw false
python scripts/pikvm_api.py msd-connect --connected true
python scripts/pikvm_api.py switch-active --port 2
python scripts/pikvm_api.py switch-atx-power --port 2 --action reset_hard

When to use which operation

Read-only inspection

• info → general PiKVM/device metadata
• atx-state → current power LED/busy state
• streamer-state → stream and capture health
• msd-state → mounted image and storage availability
• switch-state → PiKVM Switch overview

Input control

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

Screen capture

• snapshot to save a JPEG locally
• ocr 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)
• atx-click to emulate case buttons
• msd-set to choose image and drive flags
• msd-connect to attach or detach the virtual drive from the host

Switch environments

• switch-active to select a target port
• switch-atx-power 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.