Skip to content

kenny — User Guide

This guide is for the operator: the person who watches the family's Windows PCs and runs commands on them through kenny. For installing and hosting the server, see setup.md.

What kenny gives you

  • An Overview dashboard — the whole fleet at a glance (health mix, inventory, security posture, the loudest problems), every figure drill-down-able to the hosts behind it.
  • A fleet view with a traffic light per machine, and a drill-down per PC: every telemetry section, a health trend, inventory changes + forecasts, and the last screenshot.
  • Two ways to act on a PC: talk to Claude (which calls kenny's tools), either from a local Claude client over MCP or from the copilot chat built into the dashboard — no local client needed, with a confirm-gate on anything that changes state.
  • Parental controls (web activity + web filter, screen time) and push alerts with a weekly digest.
  • One-click agent installer download (and a shareable link) plus server-triggered updates.

Two guides

This page is the task-oriented walkthrough. For an exhaustive, screenshot-by-screenshot tour of every tab, widget, and popup, see the Dashboard reference.

The pieces

flowchart LR
  Operator(("Operator"))
  subgraph Server["kenny-server (cloud)"]
    UI["Dashboard + Chat<br/>/ , /api/*"]
    MCP["MCP endpoint<br/>/mcp"]
    Tunnel["Agent tunnel<br/>/agent/ws"]
    Store[("Telemetry store<br/>SQLite")]
  end
  Claude["Claude<br/>(local client, optional)"]
  Agent["kenny-agent<br/>(Windows PC)"]

  Operator -->|"https + login"| UI
  Operator -->|"chat"| UI
  Operator --> Claude -->|"MCP (OAuth)"| MCP
  UI --> Tunnel
  MCP --> Tunnel
  Tunnel <-->|"WSS, agent dials out"| Agent
  Agent -->|"telemetry push"| Store
  Store --> UI

The agent always dials out to the server (NAT/firewall friendly) and authenticates with its own per-agent token; you authenticate to the server with the operator token.

Signing in

  1. Open the server in a browser (e.g. https://kenny.example.com/).
  2. You are redirected to /login. Enter the operator token (set by whoever runs the server as KENNY_OPERATOR_TOKEN). A cookie keeps you signed in; /logout clears it.

The web UI and a local Claude client are two separate front doors to the same account. The browser uses this login cookie; Claude Desktop uses the OAuth flow (see Option B below), signing in with these same credentials and approving the connection once.

The Overview tab

The landing view is a high-level dashboard built from every PC's latest snapshot: KPI tiles (hosts online, reboots pending, open/failed updates, quarantine, EOL, disks filling), a fleet health donut, an inventory breakdown (OS + laptop/desktop), a security posture row (encryption, Defender real-time, firewall), a problem sections bar, a top hosts ranking, a problem-flow Sankey, a reliability heatmap, and a fleet health trend. Every segment, bar, node, cell, and KPI is clickable — it opens a table of the hosts behind that number, and clicking a host jumps straight to it. Full details in the dashboard reference.

The fleet view

Each PC is a tile with a status dot:

Dot Status Meaning
🟢 ok nothing flagged
🟡 warn something needs attention (e.g. disk > 80 %, aging battery)
🔴 crit acute problem (e.g. Defender real-time protection off, disk ≥ 95 %)
⚪ unknown/offline no recent telemetry / agent not connected

The header shows the worst-of health across the whole fleet. Click a tile to drill in.

The agent drill-down

  • Sections — each telemetry section with its status, a one-line summary, and the server's health rule reason. Click a section tile to open a popup with its details rendered as readable tables and fields (no raw JSON). For a flagged section, when an Anthropic API key is configured, an AI Recommendation (Diagnosis / Action / Urgency) streams in at the top, sometimes with an Auto-Remediate button that hands a fix prompt to the copilot.
  • AI Forecast — a short, plain-English outlook pinned at the top of the drill-down: what is likely to need attention on this PC soon, drawn from the disk-fill and battery trends and the inventory changes since yesterday. With an Anthropic API key the model writes it (marked ✦); without a key the same card shows a concise deterministic summary.
  • Health trend — recent snapshots as a sparkline.
  • Last screenshot — the most recent desktop capture, with a recapture button.
  • Action buttons: refresh, remote help (Quick Assist), reinstall, re-share, update. Onboarding a new PC uses the Add a PC panel (installer / share link); from a PC's drill-down, reinstall / re-share re-provision that existing PC (rotating its token).

kenny reports around 30 telemetry sections — disk & SMART, memory, CPU/thermals, uptime, network & routing, Wi‑Fi, Defender (+ quarantine), third-party AV, firewall, BitLocker, Windows Update & app updates, reboot-pending, OS support/EOL, services, autostart, scheduled tasks, peripherals, printers, local accounts, listening ports, backup status, battery, reliability, time sync, web activity, and screen time. Health thresholds are evaluated server-side (authoritative); the agent also sets a reasonable per-section status. See the telemetry reference for every section and its rule.

The fleet-wide observability lives on the Activity tab: a searchable, paged tool-call audit log (read-only vs state-changing, ok/err) and an events & logs stream (server + agent log lines and emitted alerts). The Flagged view — reached from the warnings / critical counts in the header — groups everything needing attention by PC for fast triage.

Running commands on a PC

Option A — the dashboard chat (no local client)

Open the chat tab and ask in plain language (“is Defender on for example-pc?”, “free up disk on example-laptop”). Claude picks the right kenny tools and runs them.

sequenceDiagram
  actor Op as Operator
  participant Chat as Dashboard chat
  participant Claude as Claude (server-side)
  participant Agent as kenny-agent
  Op->>Chat: "Update 7-Zip on example-pc"
  Chat->>Claude: message + tool catalog
  Claude-->>Chat: read-only tool calls (diag/telemetry)
  Chat->>Agent: forwarded (auto-run)
  Agent-->>Chat: results
  Claude-->>Chat: wants winget_install (state-changing)
  Chat-->>Op: ⚠ confirmation required (tool + args)
  Op->>Chat: confirm
  Chat->>Agent: winget_install
  Agent-->>Chat: result
  Claude-->>Op: summary

Confirm-gate: read-only tools (diagnostics, fs_read/list/search, telemetry_collect, *_list, screen_capture) run automatically. Anything state-changing — powershell_exec, winget_install/uninstall/update, net_dns_flush, net_adapter_reset, agent_update — pauses for your explicit confirmation before it runs. Every call is recorded in the tool-call log.

The chat mirrors your fleet selection: the context chip shows whether it's scoped to the selected PC or the whole fleet. Conversations are saved — new starts a fresh one and history browses, resumes, or deletes past ones. See the tool reference for the full catalog and the dashboard reference for the copilot in detail.

Option B — a local Claude client over MCP

kenny is a remote MCP server with a built-in OAuth 2.1 authorization flow (ADR-0041), so connecting Claude Desktop takes no token copy-paste:

  1. In Claude Desktop, open Settings → Connectors → Add custom connector.
  2. Enter the server's MCP URL — https://<server>/mcp — and continue.
  3. Claude opens kenny's sign-in page. Log in with your kenny username and password (and 2FA code if you enabled it), the same credentials as the web dashboard.
  4. Approve the one-time "Allow this connection?" consent screen. Claude stores the resulting token and reconnects automatically from then on.

The connection acts as your account: the same tools are available and select_agent chooses the target PC, all within your role and host scope. Revoke it any time by disabling the grant (or resetting your password) — see the dashboard reference.

Scripts and other MCP clients that can't do the OAuth handshake can still authenticate with a personal access token: mint one under Profile → personal access tokens and send it as Authorization: Bearer <pat> to https://<server>/mcp.

Tool catalog

Family Tools Changes state?
Shell powershell_exec ✅
Packages winget_list · winget_install · winget_uninstall · winget_update install/uninstall/update ✅
Files fs_list · fs_search · fs_read · fs_disk_usage read-only
Diagnostics diag_processes · diag_services · diag_eventlog · diag_autostart read-only
Network net_config · net_dns_flush · net_adapter_reset dns_flush/adapter_reset ✅
Screen screen_capture read-only
Telemetry telemetry_collect read-only
Agent mgmt agent_update ✅
Server-only list_agents · select_agent · fleet_overview · agent_health · agent_snapshot read-only

Parental-controls tools (webfilter_apply/clear, webfilter_get/set/push, web_activity_query) are covered in Parental controls. The tool reference has the complete catalog with arguments and the state-changing classification.

The local kill switch (endpoint user)

The person sitting at a managed PC can switch remote control off at any time from the kenny tray icon (notification area) → Fernsteuerung aktiv. While off, the agent refuses every state-changing tool above (the ✅ rows) and a forwarded call comes back with error.code = "disabled"; telemetry and all read-only tools keep working, so the fleet view stays live. Remote control is on by default and the choice persists across restarts. The tray icon shows the state at a glance (normal Kenny = on, greyed with a red slash = off). To re-enable, open the menu and toggle it back on. See ADR-0011.

Adding a PC to the fleet

From the Add a PC panel (left of the console), installer gives you a ZIP (the agent binary + an install.bat pre-filled with the server URL, the agent's id, and a freshly minted token). Or use share link to send the target user a one-time, expiring download link they can open without your login. For a PC that already exists, the drill-down's reinstall / re-share buttons do the same for that agent id (rotating its token, so the old install stops reporting).

sequenceDiagram
  actor Op as Operator
  participant UI as Dashboard
  participant User as Target user (Windows)
  participant Agent as kenny-agent
  participant Server as kenny-server
  Op->>UI: download installer / share link
  UI-->>Op: ZIP (exe + install.bat + token)
  Op-->>User: send link / ZIP
  User->>Agent: run install.bat (as Admin)
  Agent->>Agent: register as auto-start Windows service
  Agent->>Server: connect (WSS) + register (token)
  Agent-->>Server: first telemetry snapshot
  Server-->>UI: new agent appears online

The installer registers the agent as an auto-starting Windows service (restart-on-failure), so it survives reboots. To remove it: kenny-agent.exe uninstall.

Updating an agent

update agent pushes a server-triggered self-update. The agent downloads the new binary from the server, verifies its SHA-256 before swapping, then a helper stops the service, replaces the binary (with rollback on failure), and restarts it.

sequenceDiagram
  actor Op as Operator
  participant Server as kenny-server
  participant Agent as kenny-agent (service)
  Op->>Server: update agent
  Server->>Agent: agent_update {version, url, sha256}
  Agent->>Server: download new binary (url)
  Agent->>Agent: verify sha256, stage
  Agent-->>Server: {ok, staged_version}
  Agent->>Agent: helper: stop → swap → restart
  Agent->>Server: reconnect on new version

Good habits for operators

  • Treat powershell_exec and the winget/net write tools as real admin power — confirm deliberately. Screenshots and fs_read can expose private content; use them sparingly.
  • Telemetry summaries come from the agent; the dashboard is for your family's machines only.
  • If a PC shows crit, open it and read the section reason before acting.
  • Rotate a PC's token (re-download the installer) if you suspect a leaked token.

See setup.md for hosting, TLS, environment variables, and releases.