Pod

Yes, this is on purpose. Pod is built for agents, so the default page is plain HTML.
Human? View the normal website.
Agent? You probably prefer /mcp/kvm-pilot/issues.md or /mcp/kvm-pilot/issues.json, or Pod over MCP.

Reported issues for kvm-pilot

Pod holds 22 of 56 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to kvm-pilot.

Most discussed

MCP: act-capability parity + human-in-the-loop confirmation (post-hardening roadmap)

After 5b851a9 the MCP server can see (info/power_state/snapshot/classify) and gate power, but an agent still cannot drive a box: no type/key, no wait_for_state, no mount/eject. For the primary audience (AI-agent builders) this is the core product gap — the unattended-install loop the README sells is not yet possible over MCP.

Acceptance criteria (MVP)

Read the thread · 2026-07-01 · closed · 9 comments

GLKVM: on-demand-streamer trigger-then-wait to recover a snapshot 503 (gated on a V1.9.1 bench proof; H.264 decoder → #151)

What happened

On a GL-RM1PE, snapshot intermittently returns:

Subsystem unavailable (HTTP 503): {"ok": false, "result": {"error": "UnavailableError", "error_msg": "Service Unavailable"}}

(raised at http.py:213–214), flapping with the stale-frame behavior (companion issue) within the same minute — the same snapshot call succeeds, then 503s, then succeeds, with no state change on our side.

classify_screen fails identically and simultaneously: both the server-side vi

Read the thread · 2026-07-06 · closed · 7 comments

Setup documentation notes and sample prompts

Here are some setup tips and sample prompts. These need to be folded into the documentation soon.

  1. pip install kvm-pilot
  2. inside your Agent's interface, "load the kvm-pilot mcp server that pip installed," and follow the prompts to enable it. On my agent, Claude Code, I have to exit the existing session to start a new MCP server, so make sure you follow the instructions to get the MCP up and running for optimal results.
  3. When you relaunch your Agent, you may get a prompt confirming you wan

Read the thread · 2026-07-04 · closed · 5 comments

Docs, visuals & brand overhaul: accuracy sweep, logo, diagrams, troubleshooting, llms.txt, README restructure

Umbrella for the 2026-07-14 documentation/marketing review (three-agent audit of repo .md, wiki, PyPI, MCP registry). Refs epic #194 (applies its "Free messaging/docs" items); progresses #171.

Audit findings being fixed

Read the thread · 2026-07-15 · closed · 3 comments

Distribution: publish server.json to the official MCP registry (io.github namespace, PyPI ownership validation)

Part of the 2026-07-13 competitive gap analysis (#194), Tier 1 item 3. Pairs with the .mcpb bundle (#148) but does not depend on it.

Problem

kvm-pilot is not listed in the official MCP registry or any downstream index (Smithery, mcp.so, Glama — which largely auto-index from the official registry and the mcp-server GitHub topic). In 2026, registry presence is how agent hosts and users discover servers; it is the highest discoverability-pe

Read the thread · 2026-07-13 · closed · 3 comments

2026-08-03 CodeRabbit whole-project review: 95 findings — triage + fix batches

Ran CodeRabbit CLI 0.7.1 over the ENTIRE project (orphan-baseline worktree so all 178 files / 46k lines appear as one reviewable diff; coderabbit review --base-commit <empty-baseline>). Result: 2 critical / 43 major / 50 minor. This issue is the triage record; fixes land in thematic commits referencing it.

Fix now — verified real (code)

Read the thread · 2026-08-04 · closed · 2 comments

Agent doctrine: periodically self-assess and pivot to the cheapest sufficient interface (browser console → CLI HID once the target is driveable)

Desired behavior

An agent operating a KVM session should periodically self-assess whether a faster / cheaper interface is now sufficient, and pivot to it — especially at phase boundaries (e.g. once the target is online and driveable). "Which interface am I using, and is there a cheaper one that still works for what I'm doing now?" should be a recurring question the agent asks itself, not a one-time choice.

Why

Interfaces to the same KVM differ by ~orders of magnitude in latency and

Read the thread · 2026-07-08 · open · 2 comments

Proposal: Community Compatibility Database (Azure PostgreSQL + Function) — alt ingestion/storage for #96

Relationship to existing issues. This proposal is an alternative implementation of the ingestion + storage + publish layer of epic #96 — it revisits the transport and evidence-store decisions currently specced in #100 (telemetry client) and #101 (ingestion + publish). Where #100/#101 chose a git-native, zero-standing-infra design (in-repo data/test_runs.jsonl ledger, repository_dispatch transport, GitHub Actions recompute-and-commit), this proposes an externally-hosted Azure PostgreSQL

Read the thread · 2026-07-03 · open · 2 comments

Most recent

CI red on main: mcp 2.1.x re-added mcp.server.fastmcp as a raising stub, so mypy fails the shim's 1.x branch (attr-defined)

Summary

main is red. Every test (3.11–3.14) job and mcp-majors (mcp>=2,<3) fail at the Mypy step:

src/kvm_pilot/mcp/_sdk.py:31: error: Module "mcp.server.fastmcp" has no attribute "Context"  [attr-defined]
src/kvm_pilot/mcp/_sdk.py:31: note: Error code "attr-defined" not covered by "type: ignore[no-redef]" comment
src/kvm_pilot/mcp/_sdk.py:31: error: Module "mcp.server.fastmcp" has no attribute "Image"  [attr-defined]
src/kvm_pilot/mcp/_sdk.py:32: error: Module "mcp.server.fas

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/256) · 2026-08-29 · closed · 0 comments

### SSH-only targets can't be healthchecked or routed — the OS plane isn't reachable without a device driver

## The gap

A machine reachable **only over SSH** — no KVM, no BMC — cannot be healthchecked or driven through the router, because those paths build a device driver first. Today:

| Command | SSH-only target |
|---|---|
| `ssh-check`, `ssh-exec`, `ssh-discover`, `ssh-bootstrap` | work ✅ |
| **`host-exec`** — *"run a command via the fastest capable **in-band** interface"* | **refuses** ❌ |
| **`healthcheck`** | **refuses** ❌ |
| `test-report`, `firmware-check` | refuse ❌ |

## Why this is inconsi

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/248) · 2026-08-04 · closed · 0 comments

### Support both MCP SDK majors (mcp>=1.10,<3) — 2.x moved FastMCP and renamed the model fields; read-only mode crashes on 2.x

## Summary

Dependabot PR #240 widens the MCP SDK dependency from `mcp>=1.10,<2` to `mcp>=1.10,<3`. As filed it fails CI on every job — which is exactly what the `<2` cap was there to prevent (#110).

mcp 2.0.0 is now a stable release, so the cap is worth removing properly rather than pinning forever.

## Why the raw bump fails

mcp 2.x is **not source-compatible** with 1.x:

- `mcp.server.fastmcp` → `mcp.server.mcpserver`, and `FastMCP` → `MCPServer`. `Context`, `Image` and `ToolError` moved wi

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/241) · 2026-07-30 · closed · 0 comments

### Destructive tools that predate the act layer (power, ssh_exec, appliance_reboot, set_boot_device, amt_enable) bypass receipts AND the operator audit trail

Found while wiring the session journal (#223): only the `_act`-helper tools (HID, mouse, media, calibrate, file_firmware_report) go through approve_or_deny → receipts → `_audit_event`. `power`, `ssh_exec`, `appliance_reboot`, `set_boot_device`, and `amt_enable` do their own env-flag + confirm check and dispatch directly — so the operator audit log (`kvm_pilot.mcp.audit`) never records a power cycle or an SSH exec, despite the README's 'every destructive invocation terminal emits one record' fram

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/234) · 2026-07-20 · closed · 0 comments

### MCP: close read-tool gaps that force agents into the CLI (events, firmware-check)

Agents habituate to the CLI partly because several capabilities are CLI-only, forcing shell-outs mid-flow: `events`, `firmware-check` (read paths), `console`/SOL, `ssh-bootstrap`. Once shelling out, they stay there (see the CLI→MCP nudges issue).

Plan: add MCP twins for the read-safe gaps — `events` (bounded, non-follow), `firmware_check` (read-only currency report; the filing path already exists as file_firmware_report). Note: `console`/SOL streaming does not fit synchronous stdio MCP — docume

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/233) · 2026-07-20 · closed · 0 comments

### Guards: drift-check the mcp/README tool table + docs/cli.md against the live surface (no generation)

The mcp/README.md tool table and docs/cli.md are hand-maintained mirrors of the code surface. Names are transitively guarded (EXPECTED_TOOLS), but a tool row's annotation claims and the CLI table's command set can drift silently.

Plan (drift-check, NOT generation): (1) test asserting the mcp/README `## Tools` table's name set == EXPECTED_TOOLS and each row's destructiveHint claim matches EXPECTED_ANNOTATIONS; (2) test comparing docs/cli.md's command table against build_parser() subcommand choic

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/232) · 2026-07-20 · closed · 0 comments

### MCP: expose doctrine playbooks as resources (kvm-pilot://doctrine/{topic})

The doctrine playbooks are tool-only today. MCP resources are the semantically correct surface for static reference content, and resource-capable clients (Claude Code) can list/read/@-mention them without a tool round-trip.

Fix: @mcp.resource("kvm-pilot://doctrine/{topic}") reusing _doctrine_topics() (~15 lines, same bytes, zero drift risk). The doctrine *tool* stays — clients without resource support, and compacted sessions that only remember tools, still need it. Verify _apply_read_only_mode 

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/231) · 2026-07-20 · closed · 0 comments

### MCP: docstring diet on the six largest tools (~45% cut, steering preserved)

Tool docstrings are an unconditional per-session token tax (~15.7KB across 31 tools). The six largest (wait_for_state 23 lines, calibrate_mouse 17, mouse 14, classify_screen 13, list_virtual_media 13, file_firmware_report 13) carry mechanism narrative that belongs in re-servable surfaces (mcp/README rows, references/interfaces.md via the doctrine tool).

Diet rule: keep the call-time contract in-schema — gates, confirm semantics, refusal causes, return-shape branching; move rationale/mechanism/e

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/230) · 2026-07-20 · closed · 0 comments

### CLI: agent-aware one-line nudges to the MCP twin (close the CLI/MCP usage asymmetry)

The MCP server is under-used relative to the CLI in agent sessions, for identifiable reasons: the CLI is zero-setup in a terminal while MCP needs registration + session restart; several capabilities are CLI-only (so agents habituate to shelling out); and nothing ever tells the agent mid-flow that a faster path exists (benchmarks: MCP reads ~0.18s vs ~1.28s CLI cold start, plus in-band images with frame_ref for safe clicks).

Fix (runtime steering, house style): when the CLI detects an agent cont

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/228) · 2026-07-20 · closed · 0 comments

### CLI: kvm-pilot install-skill — put the bundled skill where Claude Code actually loads it

The bundled Claude skill ships in the wheel but nothing installs it where Claude Code discovers skills (~/.claude/skills). Docs say "pip install brings the skill" — true of bytes, false of discovery. The only runtime delivery is the MCP `doctrine` tool.

Fix: `kvm-pilot install-skill` — copies (not symlinks: survives venv recreation and wheel upgrades) SKILL.md + references/*.md into ~/.claude/skills/kvm-pilot with a provenance marker (.installed-by-kvm-pilot.json {version, installed_at}); idemp

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/226) · 2026-07-20 · closed · 0 comments

### MCP healthcheck tool bypasses the preflight cache + firmware-delta path

The MCP `healthcheck` tool calls `run_healthcheck` directly (server.py:340-352), bypassing the preflight path: no HealthCache consult, no firmware-delta finding, no acknowledgement handling — while the implicit `_preflight` on driver build has all three. The explicitly requested report is *weaker* than the automatic gate, and each healthcheck call double-audits (driver build preflight + the tool's own full run).

Fix: build the driver with `preflight=False`, then `preflight(kvm, cache=HealthCach

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/225) · 2026-07-20 · closed · 0 comments

### act: GATE_CLOSED / ssh / consent_off refusals leak the ALLOW_* env-var incantation — align to stay-mum

The `GATE_CLOSED` denial in act.py `_decide` interpolates the literal `ALLOW_*` env-var name into the refusal ("by setting KVM_PILOT_MCP_ALLOW_POWER in the server's own environment...") — contradicting the stay-mum refusal doctrine act.py itself documents ("unlike the ALLOW_* refusals, which stay mum") and that the power/appliance refusal tests enforce. `ssh_exec` (server.py:~1492) and `amt_enable consent_off` (server.py:~969-973) refusals also name their env vars.

The point of stay-mum: never 

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/224) · 2026-07-20 · closed · 0 comments

### MCP: session re-anchor tool + in-memory act journal + last-wait breadcrumb (long-session compaction resilience)

A compacted or resumed agent session cannot ask "what have I done on this device, what am I allowed to do, what was I waiting for": frame generations, receipts, the act audit trail (logger-lines-only, act.py:533-559), and wait_for_state breadcrumbs are all invisible or ephemeral. Long installs span hours; context compaction loses the earlier turns.

Plan (from the 2026-07-20 instruction-design audit):
- New read-only, offline, never-raising `session` MCP tool: server posture (read_only, dry_run,

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/223) · 2026-07-20 · closed · 0 comments

### First-class-driver gaps: test-report + CLI/MCP break on non-kvmd drivers

Surfaced by the AMT first-class-citizen sweep (#211). AMT is the first minimal-HID / PNG-snapshot / pixel-native driver, so it exposed a cluster of cross-cutting assumptions that would break **any** future driver of that shape. Fixing them project-wide with guard tests to enforce the standard.

### Bugs (all fixed in this sweep)
1. **`test-report probe_snapshot` was JPEG-only** → AMT's working PNG BIOS screenshot recorded as a **FAIL**. Now accepts JPEG *or* PNG. Affects any PNG-producing driver

[Read the thread](https://github.com/DustinTrap/kvm-pilot/issues/214) · 2026-07-18 · closed · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/DustinTrap/kvm-pilot/issues).