{"id":50798029,"url":"https://github.com/t11z/kenny","last_synced_at":"2026-06-12T16:03:53.715Z","repository":{"id":362978881,"uuid":"1259651321","full_name":"t11z/kenny","owner":"t11z","description":"Self-hosted remote administration and fleet monitoring for Windows PCs in a family setting, operated through Claude (MCP) and a web dashboard.","archived":false,"fork":false,"pushed_at":"2026-06-06T21:08:52.000Z","size":646,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T21:17:59.209Z","etag":null,"topics":["ai","claude","claude-code","family-it","fleet-management","llm","mcp","mcp-server","orchestration","remote-control","rust","windows"],"latest_commit_sha":null,"homepage":"https://t11z.github.io/kenny/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t11z.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"tsprock","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-06-04T18:10:18.000Z","updated_at":"2026-06-06T20:29:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/t11z/kenny","commit_stats":null,"previous_names":["t11z/kenny"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/t11z/kenny","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Fkenny","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Fkenny/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Fkenny/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Fkenny/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t11z","download_url":"https://codeload.github.com/t11z/kenny/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t11z%2Fkenny/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34251778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-code","family-it","fleet-management","llm","mcp","mcp-server","orchestration","remote-control","rust","windows"],"created_at":"2026-06-12T16:03:53.010Z","updated_at":"2026-06-12T16:03:53.710Z","avatar_url":"https://github.com/t11z.png","language":"Rust","funding_links":["https://ko-fi.com/tsprock"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/assets/kenny-mark-64.png\" alt=\"kenny\" width=\"72\" height=\"72\" /\u003e\n\n# 🐕 kenny\n\n**Self-hosted remote administration _and fleet monitoring_ for Windows PCs, driven by Claude (MCP) and a web dashboard.**\n\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-E8A33D.svg)](LICENSE)\n[![CI](https://github.com/t11z/kenny/actions/workflows/ci.yml/badge.svg)](https://github.com/t11z/kenny/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/badge/docs-mkdocs-E8A33D.svg)](https://t11z.github.io/kenny/)\n[![Release](https://img.shields.io/github/v/release/t11z/kenny?color=E8A33D)](https://github.com/t11z/kenny/releases)\n\n\u003c/div\u003e\n\nkenny started as a way to look after the family's Windows PCs — keep an eye on disk space and\nDefender, fix things over the phone without \"can you read me what it says\" — operated through\nClaude instead of a clunky console. It works for any small fleet you administer with consent.\n\n```mermaid\nflowchart LR\n  Operator((\"Operator\"))\n  Claude[\"Claude\u003cbr/\u003e(local client, optional)\"]\n  subgraph Server[\"kenny-server (cloud)\"]\n    UI[\"Dashboard + Chat\"]\n    MCP[\"MCP endpoint /mcp\"]\n    Tunnel[\"Agent tunnel /agent/ws\"]\n    Store[(\"Telemetry store\u003cbr/\u003eSQLite\")]\n  end\n  Agent[\"kenny-agent (Windows PC)\u003cbr/\u003ePowerShell · Win32 · winget\u003cbr/\u003efilesystem · screenshot · collectors\"]\n\n  Operator --\u003e|https dashboard + chat| UI\n  Operator --\u003e Claude --\u003e|MCP, Bearer token| MCP\n  UI --\u003e Tunnel\n  MCP --\u003e Tunnel\n  Tunnel \u003c--\u003e|WSS, agent dials out| Agent\n  Agent --\u003e|telemetry push| Store\n  Store --\u003e UI\n```\n\n- **kenny-server** (Python / FastMCP): stable MCP endpoint for Claude, the agent tunnel,\n  the telemetry store (SQLite), and the operator dashboard. One ASGI app, one port.\n- **kenny-agent** (Rust, single binary): runs on each Windows PC, dials **out** to the\n  server (NAT/firewall friendly), executes tool calls in the user's session, and pushes\n  periodic health snapshots.\n\n## ✨ Features\n\n### Fleet monitoring\n- **Push telemetry** from each PC (default every 15 min, plus an immediate first push),\n  persisted in SQLite with ~30-day retention and a per-agent history.\n- **~25 telemetry sections**: disk + SMART, memory, processes, CPU/thermals, uptime,\n  network + routing, Wi‑Fi quality, Defender (+ quarantine), third-party AV, firewall,\n  BitLocker encryption, Windows Update + app updates, reboot-pending, OS support/EOL,\n  services, autostart, peripherals, printers, battery, reliability, time sync.\n- **Server-side health rules** (authoritative): e.g. disk \u003e 80 % ⇒ warn / ≥ 95 % ⇒ crit,\n  Defender real-time off ⇒ crit, with worst-of roll-up per agent and across the fleet.\n\n### Operator dashboard (web UI)\n- Fleet view with a **traffic-light** per PC and the fleet's worst-of health.\n- Per-agent **drill-down**: each telemetry section with status + rule reason (click a section for a\n  structured detail popup), a **health trend**, and a searchable, paged **tool-call audit log**.\n- Action buttons: refresh now, **remote help** (Quick Assist), reinstall, re-share, update agent;\n  onboard a new PC from **Add a PC** (installer / share link).\n- Single-page, dependency-light; cookie login at `/login`.\n\n### Remote administration — capability tools\n- **Shell**: `powershell_exec`\n- **Packages**: `winget_list` · `winget_install` · `winget_uninstall` · `winget_update`\n- **Files**: `fs_list` · `fs_search` · `fs_read` · `fs_disk_usage`\n- **Diagnostics**: `diag_processes` · `diag_services` · `diag_eventlog` · `diag_autostart`\n- **Network**: `net_config` · `net_dns_flush` · `net_adapter_reset`\n- **Screen**: `screen_capture` · **Remote help**: `remotehelp_status` · `remotehelp_start` ·\n  `remotehelp_stop` (Quick Assist concierge) · **Telemetry**: `telemetry_collect` ·\n  **Agent mgmt**: `agent_update`\n- **Server-only orchestration**: `list_agents` · `select_agent` · `fleet_overview` ·\n  `agent_health` · `agent_snapshot`\n- Windows-only tools have **portable Linux fallbacks**, so the agent builds and runs in CI/dev.\n\n### Two ways to drive it with Claude\n- **Local MCP client** → `/mcp` (FastMCP Streamable HTTP), operator token as bearer.\n- **Server-hosted chat** in the dashboard (no local client): a Claude tool-use loop bridged to the\n  same tools, with prompt-cached system + tool schemas; model configurable (default\n  `claude-sonnet-4-6`).\n- **Confirm-gate**: read-only tools auto-run; state-changing tools (`powershell_exec`, `winget`\n  writes, `net_dns_flush`/`adapter_reset`, `remotehelp_start`/`_stop`, `agent_update`) require\n  explicit operator confirmation.\n\n### Agent distribution \u0026 lifecycle\n- **One-click installer download** from the GUI: a prebuilt binary + a generated `install.bat`\n  carrying the server URL, agent id, and a freshly minted token.\n- **Expiring, one-time shareable link** (`/d/…`) for the target user — no operator login needed.\n- **Windows service**: self-install (`install` / `uninstall` / `run-service`) via the\n  `windows-service` crate, auto-start with restart-on-failure recovery.\n- **Server-triggered self-update** (`agent_update`): download → SHA‑256 verify → staged swap with\n  rollback → service restart; the agent reconnects on the new version.\n\n### Transport \u0026 connectivity\n- Agent **dials out** over WSS (NAT/firewall friendly) and never listens.\n- **Frozen, versioned JSON wire contract** (`PROTOCOL_VERSION 0.7`) with golden fixtures\n  round-tripped by both sides; request/response correlation, ping/pong heartbeat, and\n  exponential-backoff reconnect.\n\n### Security \u0026 auth\n- **Operator bearer token** for MCP + API + UI (multiple operator tokens supported); cookie login\n  with the `Secure` flag under TLS.\n- **Per-agent tokens** in a SQLite token store with a **rotation endpoint**; the agent authenticates\n  on `register`.\n- A **local kill-switch** (tray) and a deterministic, always-on **agent-side safety guard** that\n  refuses individually dangerous calls regardless of operator approval.\n- TLS server identity (`wss`), confirm-gate for destructive actions, and a tool-call audit log.\n\n### Engineering\n- **Contract-first** (`docs/protocol.md` + `docs/fixtures/`), **ADRs** (MADR) for every significant\n  decision, and Claude Code **skills/commands + subagents** for repeatable changes.\n\n## 📚 Documentation\n\nThe full docs site: **\u003chttps://t11z.github.io/kenny/\u003e** (built from `docs/` with MkDocs Material).\n\n- **[User guide](docs/user-guide.md)** — operator workflows: dashboard, chat, running tools,\n  adding/updating agents (with diagrams).\n- **[Setup \u0026 operations](docs/setup.md)** — hosting, environment variables, TLS, building \u0026\n  distributing the agent, releases.\n- **[Wire protocol](docs/protocol.md)** + **[fixtures](docs/fixtures)** — the agent⇄server contract\n  (single source of truth; both sides round-trip the fixtures so they cannot drift).\n- **[Architecture decisions](docs/adr)** — MADR records for every significant decision.\n\n## 🚀 Quickstart\n\n```bash\n# Server (Docker Compose): dashboard, MCP endpoint, agent tunnel on one port\ncp .env.example .env   # set KENNY_OPERATOR_TOKEN etc. (see docs/setup.md)\ndocker compose up -d\n```\n\nThen open the dashboard, use **Add a PC** to download an installer for each Windows machine. Full\ndetails — TLS, environment variables, building the agent — are in **[docs/setup.md](docs/setup.md)**.\n\n## 🛠️ Develop\n\n```bash\n# server\ncd kenny-server \u0026\u0026 pip install -e \".[dev]\" \u0026\u0026 pytest\n\n# agent (builds on Linux too, via cfg fallbacks)\ncd kenny-agent \u0026\u0026 cargo test \u0026\u0026 cargo build\n```\n\nHelper commands inside Claude Code: `/new-adr`, `/add-tool`, `/add-collector`,\n`/contract-check`, `/e2e`, `/security-review`. See **[CONTRIBUTING.md](CONTRIBUTING.md)**.\n\n## 🤝 Community \u0026 contributing\n\n- **[Contributing guide](CONTRIBUTING.md)** — build/test, the contract-first workflow, and how to\n  add a tool or a telemetry collector.\n- **[Code of Conduct](CODE_OF_CONDUCT.md)** — Contributor Covenant.\n- **[Security policy](SECURITY.md)** — please report vulnerabilities **privately**, never in a\n  public issue (kenny is a remote-admin tool).\n- Questions and ideas: **[GitHub Discussions](https://github.com/t11z/kenny/discussions)**.\n\n## 📄 License\n\nkenny is licensed under the **GNU Affero General Public License v3.0** ([AGPL-3.0-only](LICENSE)).\nBecause the server is network-facing, the AGPL's §13 means anyone who runs a modified kenny as a\nservice must offer its source to users.\n\n## Status\n\nBoth components are implemented against the contract: capability tools, telemetry collectors +\nhealth rules, the fleet dashboard, a server-hosted Claude chat (with a confirm-gate for\nstate-changing tools), operator + agent auth (token store with rotation), the Windows service +\nserver-triggered self-update, agent installer download, Docker/Compose, and a GHCR release\nworkflow. Runtime-only Windows behaviors (service control, live self-update swap, Quick Assist)\nare compile-verified via cross-build and the Windows CI job; real-hardware verification, TLS\nhardening, and code-signing are operational follow-ups (see `docs/adr/`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft11z%2Fkenny","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft11z%2Fkenny","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft11z%2Fkenny/lists"}