picokvm-client

Python client for the Luckfox PicoKVM. A thin, synchronous wrapper around its JSON-RPC 2.0 API (POST /api/rpc) and cookie-auth endpoint (POST /auth/login-local), built on httpx and jsonrpcclient.

Unofficial. Independent, community-built client. Not affiliated with, authorized by, or endorsed by Luckfox or JetKVM. "PicoKVM" and "JetKVM" belong to their respective owners and are used here only to describe compatibility. No vendor source code is included; this reimplements the device's public JSON-RPC protocol and standard USB HID Boot-Protocol reports.

Compatibility

Targets the Luckfox PicoKVM. Its firmware is a Luckfox-Pico fork of JetKVM, so the wire protocol currently overlaps with JetKVM and its other forks. This client is only tested against the PicoKVM and makes no compatibility promise to JetKVM; a JetKVM is better served by a dedicated jetkvm-client.

Install

pip install picokvm-client
# or
uv add picokvm-client

CLI

The package installs a picokvm command:

export PICOKVM_URL=http://kvm.example PICOKVM_PASSWORD=hunter2

picokvm ping
picokvm device-id
picokvm video-state
picokvm type "hello world"
picokvm combo "Ctrl+Alt+Del"
picokvm rpc getJigglerState

--url and --password override the environment variables. Run picokvm --help for the full command list.

Safety. The HID commands (type, key, combo, click) inject input into whatever host is attached to the KVM. A mistake can lock the keyboard, type into the wrong window, or click at random coordinates. Test against a throwaway target before using these in automation.

Library

from picokvm_client import PicoKVMClient

with PicoKVMClient("http://kvm.example", password="hunter2") as kvm:
    if not kvm.ping():
        raise RuntimeError("KVM not responding")

    state = kvm.get_video_state()
    print(f"Video: {state.width}x{state.height}, ready={state.ready}")

    kvm.key_combo("Ctrl+Alt+Del")
    kvm.type_text("hello world\n")
    kvm.click(state.width // 2, state.height // 2)

    kvm.mount_with_http("https://files.example.com/installer.iso")
    kvm.trigger_reset()

The client owns an httpx.Client that holds the session cookie. Use it as a context manager so the connection pool and cookie are released on exit.

Methods

Common operations have typed methods. Anything else on the device is reachable through client.rpc(method, **params), a generic JSON-RPC call.

Exceptions

All exceptions inherit from PicoKVMError (itself a plain Exception, no third-party base). Each carries advisory exit_code, hint, and retryable attributes that a caller can map onto its own error type.

Examples

Runnable scripts in examples/ (each reads PICOKVM_URL and PICOKVM_PASSWORD):

Testing

Tests drive the client through httpx.MockTransport, so no sockets are opened. Each typed method asserts the exact JSON-RPC method and params it puts on the wire.

The HID commands (type_text, click, key_press, key_combo) are checked at the payload level only, not against real hardware. Run a manual smoke test on a throwaway target before relying on them.

Development

uv sync --extra dev
pre-commit install --install-hooks
pre-commit install --hook-type commit-msg
git config commit.template .gitmessage

Checks: uv run pytest, uv run ruff check src tests, uv run mypy src/picokvm_client --strict. Commit messages follow .gitlint (subject 10 to 72 chars, body wrapped at 72, Signed-off-by required, so use git commit -s).

Issues

File issues at https://github.com/onurcelep/picokvm-client/issues.