kache-ssh 0.1.0__tar.gz

kache_ssh-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/

kache_ssh-0.1.0/AGENTS.md

@@ -0,0 +1,37 @@
+# Working on Kache
+
+**Using Kache** (sending orders, reading the feed, MCP): read
+[src/kache/AGENTS.md](src/kache/AGENTS.md), which is also printed by `kache guide`.
+
+**Changing Kache:**
+
+- Setup: `python -m venv .venv`, then `.venv/Scripts/pip install -e ".[dev]"`
+  (Windows) or `.venv/bin/pip install -e ".[dev]"`.
+- Tests: `python -m pytest -q`. They start real gatekeepers on 127.0.0.1
+  with temporary state folders and test through the real SSH path, the CLI
+  (subprocesses), the MCP server and the Textual app (`run_test`).
+
+Layout (`src/kache/`):
+
+| file | role |
+|---|---|
+| `agent.py` | the gatekeeper: SSH server, internal `kache:` requests, orders, feed, pairing |
+| `client.py` | connecting (address race, key pinning), orders, pairing, device list |
+| `probe.py` | status snapshots, Tailscale discovery, `doctor` (shared by CLI, MCP, TUI) |
+| `network.py` | Tailscale and interface addresses, listen modes |
+| `cli.py` | the `kache` command |
+| `tui.py` | the Kache terminal (Textual) |
+| `mcp.py` | MCP server over stdio |
+| `evidence.py`, `telemetry.py` | failure reports, health numbers |
+| `config.py`, `keys.py`, `service.py` | state folder, device key, autostart |
+
+Rules:
+
+- Bump `PROTOCOL` in `__init__.py` when gatekeepers of different versions
+  could misread each other.
+- Bump `SCHEMA` when a JSON shape that agents read changes incompatibly, and
+  update `src/kache/AGENTS.md` with it.
+- The client must only ever offer the device key. `_DeviceKeyClient` exists
+  because asyncssh would otherwise add ssh-agent keys first.
+- Windows orders run from a temporary UTF-8 `.ps1` (`-File`), not
+  `-EncodedCommand`, which turns errors into CLIXML.

kache_ssh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Malm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kache_ssh-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: kache-ssh
+Version: 0.1.0
+Summary: Kache: one terminal to command all your devices over SSH, with a gatekeeper agent on every device.
+Author: Simon Malm
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,fleet,mcp,orchestration,remote,ssh,tailscale,terminal,tui
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: asyncssh>=2.14
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: textual>=8.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: nvidia-ml-py>=12; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# Kache
+
+One terminal to command all your devices.
+
+Kache is a hub that runs in your terminal. Pair your computers once, then
+type a command and it runs on the device you picked, or on all of them at
+once, exactly as if you were sitting at that machine. Every device runs a
+small **gatekeeper** that only obeys devices you paired, refuses orders that
+cannot work there, and sends back an evidence report when something fails.
+Every order anyone sends (you, a script, or an AI agent working for you)
+shows up in the live feed with the exact command.
+
+```
+pip install kache-ssh
+kache
+```
+
+## What you get
+
+- **A real remote terminal.** What you type is what runs on the other device,
+  in its own shell (PowerShell on Windows, your shell on Linux and macOS).
+  `cd` sticks between commands, output streams live, Ctrl+C stops an order.
+- **One device or all of them.** Pick a device, or press F6 and send the same
+  order to every device in parallel; output is labelled per device.
+- **Device health at a glance.** Online/offline, CPU and RAM use, GPU load,
+  temperature and memory (NVIDIA), and CPU temperature where the OS exposes it.
+- **Pairing with a yes/no question.** Ask another device to pair; its Kache
+  terminal asks *"laptop wants to send orders to this device. Code 482 913.
+  Accept?"* Both screens show the same code, so nobody can sit in between.
+- **Works at home and away.** Kache remembers every address of a device (LAN,
+  Tailscale IP, Tailscale name) and uses whichever answers. Pair once at
+  home; it keeps working over [Tailscale](https://tailscale.com) anywhere.
+- **A gatekeeper on every device.** Unknown devices can only say hello or ask
+  to pair. Paired devices are pinned by key. Orders for commands that do not
+  exist on that device are refused up front (Linux/macOS) or explained
+  afterwards (Windows).
+- **Evidence when things break.** A failing order comes back with a report:
+  exit code, last lines of output, labelled hints (command not found,
+  permission, disk full, missing Python module, network, out of memory...)
+  and the machine's state at that moment.
+- **A live feed of every order.** Who sent what to which device, when, and
+  how it ended, including orders from scripts and AI agents, which are
+  labelled with the agent's name.
+- **Built for AI agents too.** Every command has `--json`, there is an MCP
+  server (`kache mcp`), and `kache guide` explains everything an agent needs.
+
+## Quick start
+
+On every device:
+
+```
+pip install kache-ssh
+kache service install     # keep the gatekeeper running at logon (recommended)
+kache                     # open the Kache terminal
+```
+
+In the Kache terminal on the device you want to command *from*, press **F2**
+and enter the other device's address: its LAN IP, Tailscale IP or Tailscale
+machine name (devices on your tailnet are listed for you). Accept on the
+other device when the codes match. It appears in your device list, and
+anything you type now runs there.
+
+On Windows, the first time the gatekeeper starts, Windows may ask whether
+Python may accept connections. Allow it on private networks.
+
+### Keys
+
+| Key        | Action                                        |
+|------------|-----------------------------------------------|
+| Enter      | send what you typed to the selected device(s) |
+| ↑ / ↓      | previous / next command                       |
+| Ctrl+↑ / ↓ | select the previous / next device             |
+| F6         | switch between one device and all devices     |
+| Ctrl+C     | stop the running order(s)                     |
+| F2         | pair a new device                             |
+| F3         | rename the selected device                    |
+| F4         | remove the selected device                    |
+| F5         | show the last failure's evidence              |
+| Ctrl+Q     | quit                                          |
+
+## Away from home: Tailscale
+
+Kache connects devices directly, so a device must be reachable from the one
+commanding it. At home that is your LAN. Away from home, install
+[Tailscale](https://tailscale.com) (free for personal use) on both devices
+and sign in with the same account. Then:
+
+- `kache discover` lists the devices on your tailnet and which run Kache;
+- pairing by Tailscale name works: `kache pair my-desktop`;
+- devices paired over LAN switch to Tailscale automatically when the LAN
+  address stops answering;
+- `kache listen tailscale` makes a gatekeeper answer on your tailnet only,
+  ignoring the local network.
+
+## For scripts and AI agents
+
+Everything the terminal does is also a command with `--json` output, and
+every order still appears in the feed:
+
+```
+kache devices --json                              # status and health of every device
+kache run desktop --json --timeout 60 -- nvidia-smi
+kache run all --as nightly-job -- git pull         # labelled in every feed
+kache feed -d all -f --json                       # live JSON-lines feed from all devices
+kache evidence E-3f2a9c -d desktop                # a failure report
+kache doctor desktop --json                       # why a device cannot be reached
+```
+
+For MCP clients (Claude Code, Claude Desktop, Cursor and others):
+
+```
+claude mcp add kache -- kache mcp
+```
+
+Agents get the tools `kache_devices`, `kache_run`, `kache_feed`,
+`kache_evidence`, `kache_doctor`, `kache_discover`, `kache_pending` and
+`kache_pair`. Accepting pair requests and revoking devices stays with
+people. `kache guide` prints the full guide: JSON shapes, feed event kinds,
+exit codes and rules for agents.
+
+## How it works
+
+Each device has one ed25519 key, created on first run. The gatekeeper is an
+SSH server (built on asyncssh, port 7722) that accepts any key but only lets
+unknown keys say hello or ask to pair; paired keys may send orders. The
+Kache terminal is an SSH client that pins each paired device's key. Nothing
+goes through a server in between.
+
+State lives in one folder per device (`kache whoami` shows where; override
+with `KACHE_HOME`): the device key, its name, the devices it commands, the
+devices trusted to command it, the feed and the evidence reports.
+
+If something does not connect, `kache doctor` checks every step (gatekeeper,
+Tailscale, each address, the device's key, the pairing) and says what to fix.
+
+## Status
+
+Version 0.1: pairing, orders, sessions, evidence, live feed, health,
+Tailscale, JSON output and MCP work on Windows, Linux and macOS.
+
+Planned:
+- full interactive sessions (`kache attach` for programs like vim or htop);
+- confirmation popups for dangerous orders;
+- pairing both directions in one step;
+- a relay for devices that cannot reach each other directly.
+
+MIT licensed.

kache_ssh-0.1.0/README.md

@@ -0,0 +1,147 @@
+# Kache
+
+One terminal to command all your devices.
+
+Kache is a hub that runs in your terminal. Pair your computers once, then
+type a command and it runs on the device you picked, or on all of them at
+once, exactly as if you were sitting at that machine. Every device runs a
+small **gatekeeper** that only obeys devices you paired, refuses orders that
+cannot work there, and sends back an evidence report when something fails.
+Every order anyone sends (you, a script, or an AI agent working for you)
+shows up in the live feed with the exact command.
+
+```
+pip install kache-ssh
+kache
+```
+
+## What you get
+
+- **A real remote terminal.** What you type is what runs on the other device,
+  in its own shell (PowerShell on Windows, your shell on Linux and macOS).
+  `cd` sticks between commands, output streams live, Ctrl+C stops an order.
+- **One device or all of them.** Pick a device, or press F6 and send the same
+  order to every device in parallel; output is labelled per device.
+- **Device health at a glance.** Online/offline, CPU and RAM use, GPU load,
+  temperature and memory (NVIDIA), and CPU temperature where the OS exposes it.
+- **Pairing with a yes/no question.** Ask another device to pair; its Kache
+  terminal asks *"laptop wants to send orders to this device. Code 482 913.
+  Accept?"* Both screens show the same code, so nobody can sit in between.
+- **Works at home and away.** Kache remembers every address of a device (LAN,
+  Tailscale IP, Tailscale name) and uses whichever answers. Pair once at
+  home; it keeps working over [Tailscale](https://tailscale.com) anywhere.
+- **A gatekeeper on every device.** Unknown devices can only say hello or ask
+  to pair. Paired devices are pinned by key. Orders for commands that do not
+  exist on that device are refused up front (Linux/macOS) or explained
+  afterwards (Windows).
+- **Evidence when things break.** A failing order comes back with a report:
+  exit code, last lines of output, labelled hints (command not found,
+  permission, disk full, missing Python module, network, out of memory...)
+  and the machine's state at that moment.
+- **A live feed of every order.** Who sent what to which device, when, and
+  how it ended, including orders from scripts and AI agents, which are
+  labelled with the agent's name.
+- **Built for AI agents too.** Every command has `--json`, there is an MCP
+  server (`kache mcp`), and `kache guide` explains everything an agent needs.
+
+## Quick start
+
+On every device:
+
+```
+pip install kache-ssh
+kache service install     # keep the gatekeeper running at logon (recommended)
+kache                     # open the Kache terminal
+```
+
+In the Kache terminal on the device you want to command *from*, press **F2**
+and enter the other device's address: its LAN IP, Tailscale IP or Tailscale
+machine name (devices on your tailnet are listed for you). Accept on the
+other device when the codes match. It appears in your device list, and
+anything you type now runs there.
+
+On Windows, the first time the gatekeeper starts, Windows may ask whether
+Python may accept connections. Allow it on private networks.
+
+### Keys
+
+| Key        | Action                                        |
+|------------|-----------------------------------------------|
+| Enter      | send what you typed to the selected device(s) |
+| ↑ / ↓      | previous / next command                       |
+| Ctrl+↑ / ↓ | select the previous / next device             |
+| F6         | switch between one device and all devices     |
+| Ctrl+C     | stop the running order(s)                     |
+| F2         | pair a new device                             |
+| F3         | rename the selected device                    |
+| F4         | remove the selected device                    |
+| F5         | show the last failure's evidence              |
+| Ctrl+Q     | quit                                          |
+
+## Away from home: Tailscale
+
+Kache connects devices directly, so a device must be reachable from the one
+commanding it. At home that is your LAN. Away from home, install
+[Tailscale](https://tailscale.com) (free for personal use) on both devices
+and sign in with the same account. Then:
+
+- `kache discover` lists the devices on your tailnet and which run Kache;
+- pairing by Tailscale name works: `kache pair my-desktop`;
+- devices paired over LAN switch to Tailscale automatically when the LAN
+  address stops answering;
+- `kache listen tailscale` makes a gatekeeper answer on your tailnet only,
+  ignoring the local network.
+
+## For scripts and AI agents
+
+Everything the terminal does is also a command with `--json` output, and
+every order still appears in the feed:
+
+```
+kache devices --json                              # status and health of every device
+kache run desktop --json --timeout 60 -- nvidia-smi
+kache run all --as nightly-job -- git pull         # labelled in every feed
+kache feed -d all -f --json                       # live JSON-lines feed from all devices
+kache evidence E-3f2a9c -d desktop                # a failure report
+kache doctor desktop --json                       # why a device cannot be reached
+```
+
+For MCP clients (Claude Code, Claude Desktop, Cursor and others):
+
+```
+claude mcp add kache -- kache mcp
+```
+
+Agents get the tools `kache_devices`, `kache_run`, `kache_feed`,
+`kache_evidence`, `kache_doctor`, `kache_discover`, `kache_pending` and
+`kache_pair`. Accepting pair requests and revoking devices stays with
+people. `kache guide` prints the full guide: JSON shapes, feed event kinds,
+exit codes and rules for agents.
+
+## How it works
+
+Each device has one ed25519 key, created on first run. The gatekeeper is an
+SSH server (built on asyncssh, port 7722) that accepts any key but only lets
+unknown keys say hello or ask to pair; paired keys may send orders. The
+Kache terminal is an SSH client that pins each paired device's key. Nothing
+goes through a server in between.
+
+State lives in one folder per device (`kache whoami` shows where; override
+with `KACHE_HOME`): the device key, its name, the devices it commands, the
+devices trusted to command it, the feed and the evidence reports.
+
+If something does not connect, `kache doctor` checks every step (gatekeeper,
+Tailscale, each address, the device's key, the pairing) and says what to fix.
+
+## Status
+
+Version 0.1: pairing, orders, sessions, evidence, live feed, health,
+Tailscale, JSON output and MCP work on Windows, Linux and macOS.
+
+Planned:
+- full interactive sessions (`kache attach` for programs like vim or htop);
+- confirmation popups for dangerous orders;
+- pairing both directions in one step;
+- a relay for devices that cannot reach each other directly.
+
+MIT licensed.

kache_ssh-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kache-ssh"
+version = "0.1.0"
+description = "Kache: one terminal to command all your devices over SSH, with a gatekeeper agent on every device."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Simon Malm" }]
+keywords = ["ssh", "remote", "orchestration", "terminal", "tui", "fleet", "tailscale", "mcp", "ai-agents"]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "asyncssh>=2.14",
+    "textual>=8.0",
+    "psutil>=5.9",
+    "platformdirs>=4.0",
+]
+
+[project.optional-dependencies]
+gpu = ["nvidia-ml-py>=12"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "build>=1.0"]
+
+[project.scripts]
+kache = "kache.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kache"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

kache_ssh-0.1.0/src/kache/AGENTS.md

@@ -0,0 +1,212 @@
+# Kache guide for scripts and AI agents
+
+Kache sends shell commands to a person's own devices (their "paired"
+devices) and keeps a live feed of every order. You can use all of it from a
+shell (`kache ... --json`) or as MCP tools (`kache mcp`). This guide is
+everything you need; `kache --help` and `kache <command> --help` list flags.
+
+## How it works
+
+- Every device runs a **gatekeeper** (an SSH server on TCP port 7722). It
+  executes orders only from devices it has paired with, and only after a
+  person said yes to the pairing on that device.
+- An **order** is one command line. It runs exactly as written in the
+  device's own shell: **PowerShell on Windows**, the user's shell
+  (`$SHELL -c`) on Linux and macOS. Check a device's `os` before writing
+  commands for it.
+- **Sessions:** `cd` is remembered per sender and session name, so
+  `cd C:\proj` followed by `git status` in the same session works like a
+  terminal. Other shell state (variables, activated venvs) does not carry
+  over: each order is a fresh shell started in the session folder.
+- **Every order is visible.** Each one appears in the feed of the device
+  that ran it, with the exact command, who sent it and how it ended. The
+  person who owns the devices may be watching live.
+- **Labels.** Orders carry a label naming who gave them. It is taken from
+  `--as`, then `$KACHE_AS`, then an AI agent's own name (`$AI_AGENT`,
+  `CLAUDECODE`). Through MCP the label is the MCP client's name. Never
+  pretend to be the human.
+- **Failures come with evidence.** When an order fails, is refused or is
+  stopped, the gatekeeper writes an evidence report: hints, the last output
+  lines, and the machine's state at that moment.
+- **Addresses.** A paired device is remembered with all of its addresses
+  (LAN IP, Tailscale IP, Tailscale name). Kache tries the one that worked
+  last first, then the others, so devices stay reachable away from home
+  when both run Tailscale.
+
+## Rules for agents
+
+1. Look before you act. Start with `kache devices --json`. It shows what
+   exists, which devices are online, their OS, and how loaded they are.
+2. Prefer read-only commands until you know the state. Ask the person before
+   anything destructive: deleting, overwriting, rebooting, killing processes,
+   or changing system settings.
+3. Always pass a timeout (`--timeout` / `timeout_seconds`). Never start
+   interactive programs; they wait forever for input. Kache has no TTY yet.
+   For long jobs, start them in the background on the device (for example
+   `Start-Process`, `nohup ... &`, or a scheduled task) and poll.
+4. Check a device's health before heavy work. A hot GPU or full RAM shows in
+   `telemetry`.
+5. Pairing needs a person. You may start one (`kache pair` / `kache_pair`)
+   and must tell the person the 6-digit code. Only they can accept it on
+   the other device. Accepting, denying and revoking are not offered to
+   agents through MCP. Do not use `kache accept` unless the person
+   explicitly tells you to.
+6. When a device cannot be reached, run `kache doctor DEVICE --json` and
+   follow its `fix` fields. Do not guess.
+
+## Commands
+
+All commands accept `--json`. JSON output is one object (pretty-printed)
+with `"v"` (the schema version, currently 1). In JSON mode, errors are
+`{"v":1,"ok":false,"error":"..."}` on stdout, with exit code 1.
+
+| Command | Does |
+|---|---|
+| `kache devices` | this device and every paired device: status and health |
+| `kache run TARGET [--as NAME] [--session S] [--timeout SEC] -- COMMAND` | send an order. TARGET is a device name, `a,b,c`, `all` (every paired device) or `this` |
+| `kache feed [-d DEVICE\|all] [-n N] [-f]` | recent events; `-f` follows live. `--json` prints JSON lines, one event per line |
+| `kache evidence ID -d DEVICE` | a failure report (always JSON) |
+| `kache doctor [DEVICE]` | connectivity diagnosis with fixes |
+| `kache discover` | Tailscale devices, and which run Kache |
+| `kache pair ADDRESS` | ask a device to accept this one (a person must accept there) |
+| `kache pending` | pair requests waiting on this device |
+| `kache whoami` | this device: name, addresses, fingerprint, listen mode |
+| `kache rename OLD NEW`, `kache remove NAME` | manage your device list |
+| `kache trusted`, `kache revoke NAME` | who may command this device |
+| `kache listen [all\|tailscale\|IP]` | which networks this gatekeeper answers on |
+| `kache name NEW` | rename this device |
+| `kache agent`, `kache service install`, `kache stop` | run, autostart, stop the gatekeeper |
+| `kache mcp` | MCP server on stdio |
+| `kache` | the interactive Kache terminal (for people) |
+
+### `kache run ... --json`
+
+```json
+{"v": 1, "ok": false, "command": "python train.py", "label": "claude-code",
+ "results": [
+  {"device": "desktop", "exit": 1, "duration": 0.84, "cwd": "C:\\proj",
+   "evidence": "E-3f2a9c", "summary": "A Python module is missing on this device.",
+   "rejected": null, "timed_out": false,
+   "stdout": "...", "stderr": "...ModuleNotFoundError: No module named 'torch'\n",
+   "evidence_report": {"...": "see Evidence below"}},
+  {"device": "pi", "exit": null, "error": "cannot reach pi (...)", "unreachable": true}
+ ]}
+```
+
+- `results` always holds one entry per target, in target order.
+- `exit` is `null` when the device could not be reached.
+- `rejected` is set when the gatekeeper refused the order before running
+  it, for example a command that is not installed on Linux or macOS, or a
+  Kache version mismatch.
+
+### `kache devices --json`
+
+```json
+{"v": 1, "devices": [
+  {"name": "desktop", "this_device": false, "online": true,
+   "address": "100.81.247.101", "addresses": ["100.81.247.101", "192.168.50.152"], "port": 7722,
+   "fingerprint": "SHA256:...", "os": "Windows 11", "kache": "0.1.0", "trusts_you": true,
+   "telemetry": {"cpu": 12.5, "cpu_temp": null, "ram": 41.0, "ram_used": 13.1, "ram_total": 31.8,
+                 "disk": 63.2, "uptime": 86400, "os": "Windows 11", "kache": "0.1.0", "time": 1760000000.0,
+                 "gpus": [{"name": "NVIDIA GeForce RTX 4060 Ti", "temp": 54, "util": 97,
+                           "mem_used": 5.2, "mem_total": 8.0}]},
+   "error": null}]}
+```
+
+- `cpu`, `ram` and `disk` are percentages; memory is in GiB.
+- `cpu_temp` is in °C, or `null` where the OS does not expose it (Windows).
+- `trusts_you: false` means the other device removed this one. Pair again.
+
+### Feed events (`kache feed --json`, `kache_feed`)
+
+One JSON object per line. All of them have `v`, `kind`, `time` (unix
+seconds), `device` (the gatekeeper that saw it) and `device_fp`. Events
+replayed from history on connect have `"replay": true`.
+
+| kind | extra fields |
+|---|---|
+| `order` | `id`, `cmd` (exact command), `sender` {`name`, `label`, `via` (`cli`/`terminal`/`mcp`), `fingerprint`, `addr`}, `cwd`, `session` |
+| `done` | `id`, `cmd`, `sender`, `exit`, `duration`, `session`; `evidence` + `summary` on failure; `rejected`; `cancelled: true` when stopped |
+| `evidence` | `id` (E-...), `order` (order id), `cmd`, `sender`, `summary`, `exit` |
+| `pair-request` | `id` (P-...), `name`, `os`, `fingerprint`, `addr`, `code` |
+| `paired` | `name`, `fingerprint`, `addr` |
+| `pair-declined` | `name`, `fingerprint`, `reason` |
+| `unpaired` | `sender`, `text` |
+| `unreachable` | `text` (from the CLI or MCP, when a device's feed could not be opened) |
+
+### Evidence reports
+
+```json
+{"id": "E-3f2a9c", "time": 1760000000.0, "device": "desktop",
+ "order": {"id": "O-1a2b3c", "cmd": "python train.py", "sender": {"...": "..."}, "cwd": "C:\\proj"},
+ "exit": 1, "duration": 0.84, "summary": "A Python module is missing on this device.",
+ "hints": [{"kind": "python-module", "text": "The Python module 'torch' is not installed on this device."}],
+ "stdout_tail": ["..."], "stderr_tail": ["..."], "command_found": true,
+ "system": {"os": "Windows 11", "machine": "AMD64", "python": "3.13.1", "kache": "0.1.0",
+            "shell": "powershell.exe", "telemetry": {"...": "..."}, "top_processes": [{"...": "..."}]}}
+```
+
+Hint kinds: `command-not-found`, `permission`, `disk-full`,
+`python-module`, `network`, `port-in-use`, `python-exception`,
+`out-of-memory`, `signal`, `cancelled`.
+
+## Exit codes (`kache run`)
+
+| code | meaning |
+|---|---|
+| 0 | the order succeeded on every target |
+| n | the order's own exit code (the highest one across several devices) |
+| 1 | Kache error: bad input, gatekeeper not running, pairing refused... |
+| 2 | at least one device could not be reached |
+| 77 | the device does not accept orders from this one (not paired) |
+| 124 | `--timeout` expired; the order was stopped on the device |
+| 126 | refused: Kache versions differ |
+| 127 | refused: the command does not exist on that device (Linux/macOS; on Windows a missing command exits 1 with a `command-not-found` hint) |
+
+## MCP
+
+Add Kache to any MCP client. In Claude Code:
+`claude mcp add kache -- kache mcp`
+
+| Tool | Arguments |
+|---|---|
+| `kache_devices` | none |
+| `kache_run` | `target`, `command`, optional `session`, `timeout_seconds` (default 120, max 3600) |
+| `kache_feed` | optional `device` (default `all`), `limit` (default 30, max 60) |
+| `kache_evidence` | `id`, `device` |
+| `kache_doctor` | optional `device` |
+| `kache_discover` | none |
+| `kache_pending` | none |
+| `kache_pair` | `address` |
+
+- Results are the same JSON as the CLI, in `structuredContent`, with a
+  text copy in `content`.
+- Each output stream keeps its last 60,000 characters per device; anything
+  cut is reported in `stdout_truncated` / `stderr_truncated`.
+- The default session is `mcp-<client name>`, so `cd` persists across
+  calls.
+
+## Files (read-only for agents)
+
+`kache whoami` prints the state folder: `%LOCALAPPDATA%\kache` on Windows,
+`~/.local/share/kache` on Linux, `~/Library/Application Support/kache` on
+macOS, or `$KACHE_HOME` if set.
+
+| file | contents |
+|---|---|
+| `feed.jsonl` | every event this gatekeeper emitted, one JSON per line (rotated at 5 MB to `feed.old.jsonl`) |
+| `evidence/E-*.json` | evidence reports |
+| `devices.json` | devices this one commands: addresses, port, pinned fingerprint |
+| `trusted.json` | devices allowed to command this one |
+| `device.json` | this device's name, port and listen mode |
+| `device_key` | this device's private key. Never read, copy or print it |
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `cannot reach X (... refused)` | the device is on, but Kache is not running there: `kache service install` on it |
+| `cannot reach X (... timed out)` | the device is off or asleep, on another network without Tailscale, or a firewall drops port 7722 |
+| `answered with a different key` | the device was reinstalled, or this is not the same device. Remove it and pair again; never ignore this |
+| exit 77 | that device no longer trusts this one: pair again |
+| a command works by hand but not through Kache | Kache uses a non-interactive shell without your profile (PowerShell `-NoProfile`). Use full paths or set variables in the command |

kache_ssh-0.1.0/src/kache/__init__.py

@@ -0,0 +1,17 @@
+"""Kache: one terminal to command all your devices.
+
+Every device runs a gatekeeper agent (an SSH server with its own rules);
+the Kache terminal pairs devices, shows their health, sends orders to one
+device or all of them, and keeps a live feed of every order anyone sends.
+"""
+
+__version__ = "0.1.0"
+
+# Bumped whenever devices running different Kache versions could
+# misunderstand each other. The gatekeeper refuses orders from other
+# protocol versions instead of guessing.
+PROTOCOL = 1
+
+# Version of the JSON shapes scripts and AI agents read (feed events, CLI
+# --json output, MCP tool results). Every feed event carries it as "v".
+SCHEMA = 1

kache_ssh-0.1.0/src/kache/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()