kache-ssh 0.1.2__tar.gz → 0.2.0__tar.gz

{kache_ssh-0.1.2 → kache_ssh-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kache-ssh
-Version: 0.1.2
+Version: 0.2.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
@@ -16,6 +16,7 @@ Requires-Python: >=3.10
 Requires-Dist: asyncssh>=2.14
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: psutil>=5.9
+Requires-Dist: segno>=1.5
 Requires-Dist: textual>=8.0
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == 'dev'
@@ -49,6 +50,14 @@ kache
   `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.
+- **Jobs that keep running.** Press F7 instead of Enter (or `kache run
+  --detach`) and the order keeps going after you close Kache or lose the
+  connection: training runs, builds, downloads. F8 shows every job, its
+  live output, and stops it.
+- **Files both ways.** `kache push` and `kache pull` copy files and whole
+  folders over the same paired connection.
+- **Phone notifications.** Get a push message when a job finishes, an
+  agent's order fails, a device goes offline or someone asks to pair.
 - **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
@@ -64,7 +73,8 @@ kache
 - **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.
+  and the machine's state at that moment. An order that "succeeded" while
+  PowerShell printed errors says so: *ok, but 3 errors were reported*.
 - **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.
@@ -101,6 +111,8 @@ Python may accept connections. Allow it, or other devices cannot reach this one.
 | ↑ / ↓      | previous / next command                       |
 | Ctrl+↑ / ↓ | select the previous / next device             |
 | F6         | switch between one device and all devices     |
+| F7         | send what you typed as a background job       |
+| F8         | jobs: watch their output live, stop them      |
 | Ctrl+C     | stop the running order(s)                     |
 | F2         | pair a new device                             |
 | F3         | rename the selected device                    |
@@ -108,6 +120,48 @@ Python may accept connections. Allow it, or other devices cannot reach this one.
 | F5         | show the last failure's evidence              |
 | Ctrl+Q     | quit                                          |
 
+### Start at boot
+
+By default the gatekeeper starts when you log in. For a computer that must
+stay reachable after a restart even when nobody logs in (a Windows Update
+reboot while you are away), run once in an administrator terminal:
+
+```
+kache service install --at-boot
+```
+
+When the computer shuts down, Kache simply stops; nothing needs saving.
+Background jobs that were running are reported as *lost* afterwards, so
+you know to start them again.
+
+## Jobs and files
+
+```
+kache run desktop --detach -- python train.py     # starts a job, prints its id
+kache jobs                                        # every job on every device
+kache logs J-3f2a9c -f                            # follow its output live
+kache cancel J-3f2a9c                             # stop it
+kache push model.pt data/ desktop:C:/proj         # copy to a device
+kache pull desktop:C:/proj/results .              # copy back
+kache run desktop -f setup.ps1                    # send a whole script
+```
+
+## Phone notifications
+
+Kache uses [ntfy](https://ntfy.sh), a free open-source push service:
+
+1. Install the **ntfy** app on your phone (App Store or Google Play).
+2. On one of your devices run `kache notify setup`. It shows a QR code;
+   scan it (or subscribe in the app to the topic it prints). All your paired
+   devices get the same setting.
+3. Run `kache notify test`.
+
+You get a message when a background job ends, an order from a script or AI
+agent fails, a device goes offline or comes back, or a device asks to pair.
+Messages contain a short summary, never command output. The topic name is
+a long random secret; anyone who knows it can read the messages, so keep it
+private, or use your own ntfy server with `--server`.
+
 ## Away from home: Tailscale
 
 Kache connects devices directly, so a device must be reachable from the one
@@ -142,9 +196,10 @@ 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
+Agents get the tools `kache_devices`, `kache_run` (optionally as a job),
+`kache_jobs`, `kache_job_log`, `kache_cancel_job`, `kache_push`,
+`kache_pull`, `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.
 
@@ -165,12 +220,13 @@ Tailscale, each address, the device's key, the pairing) and says what to fix.
 
 ## Status
 
-Version 0.1.2: pairing, orders, sessions, evidence, live feed, health,
+Version 0.2: pairing, orders, sessions, evidence, live feed, health,
+background jobs, file transfer, phone notifications, start at boot,
 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;
+- permissions per sender: read-only scripts and agents, your approval for dangerous orders;
 - pairing both directions in one step;
 - a relay for devices that cannot reach each other directly.
 

{kache_ssh-0.1.2 → kache_ssh-0.2.0}/README.md

@@ -1,150 +1,205 @@
-# 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, one command:
-
-```
-pip install kache-ssh
-```
-
-Then open Kache by typing `kache`. The first time, it also starts its
-gatekeeper in the background and from then on at every login, so the device
-stays reachable when the window is closed (`kache service uninstall` turns
-that off, `kache service status` shows it). No administrator rights needed.
-
-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, or other devices cannot reach this one.
-
-### 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.2: 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
+
+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.
+- **Jobs that keep running.** Press F7 instead of Enter (or `kache run
+  --detach`) and the order keeps going after you close Kache or lose the
+  connection: training runs, builds, downloads. F8 shows every job, its
+  live output, and stops it.
+- **Files both ways.** `kache push` and `kache pull` copy files and whole
+  folders over the same paired connection.
+- **Phone notifications.** Get a push message when a job finishes, an
+  agent's order fails, a device goes offline or someone asks to pair.
+- **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. An order that "succeeded" while
+  PowerShell printed errors says so: *ok, but 3 errors were reported*.
+- **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, one command:
+
+```
+pip install kache-ssh
+```
+
+Then open Kache by typing `kache`. The first time, it also starts its
+gatekeeper in the background and from then on at every login, so the device
+stays reachable when the window is closed (`kache service uninstall` turns
+that off, `kache service status` shows it). No administrator rights needed.
+
+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, or other devices cannot reach this one.
+
+### 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     |
+| F7         | send what you typed as a background job       |
+| F8         | jobs: watch their output live, stop them      |
+| 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                                          |
+
+### Start at boot
+
+By default the gatekeeper starts when you log in. For a computer that must
+stay reachable after a restart even when nobody logs in (a Windows Update
+reboot while you are away), run once in an administrator terminal:
+
+```
+kache service install --at-boot
+```
+
+When the computer shuts down, Kache simply stops; nothing needs saving.
+Background jobs that were running are reported as *lost* afterwards, so
+you know to start them again.
+
+## Jobs and files
+
+```
+kache run desktop --detach -- python train.py     # starts a job, prints its id
+kache jobs                                        # every job on every device
+kache logs J-3f2a9c -f                            # follow its output live
+kache cancel J-3f2a9c                             # stop it
+kache push model.pt data/ desktop:C:/proj         # copy to a device
+kache pull desktop:C:/proj/results .              # copy back
+kache run desktop -f setup.ps1                    # send a whole script
+```
+
+## Phone notifications
+
+Kache uses [ntfy](https://ntfy.sh), a free open-source push service:
+
+1. Install the **ntfy** app on your phone (App Store or Google Play).
+2. On one of your devices run `kache notify setup`. It shows a QR code;
+   scan it (or subscribe in the app to the topic it prints). All your paired
+   devices get the same setting.
+3. Run `kache notify test`.
+
+You get a message when a background job ends, an order from a script or AI
+agent fails, a device goes offline or comes back, or a device asks to pair.
+Messages contain a short summary, never command output. The topic name is
+a long random secret; anyone who knows it can read the messages, so keep it
+private, or use your own ntfy server with `--server`.
+
+## 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` (optionally as a job),
+`kache_jobs`, `kache_job_log`, `kache_cancel_job`, `kache_push`,
+`kache_pull`, `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.2: pairing, orders, sessions, evidence, live feed, health,
+background jobs, file transfer, phone notifications, start at boot,
+Tailscale, JSON output and MCP work on Windows, Linux and macOS.
+
+Planned:
+- full interactive sessions (`kache attach` for programs like vim or htop);
+- permissions per sender: read-only scripts and agents, your approval 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.2 → kache_ssh-0.2.0}/pyproject.toml

@@ -1,42 +1,43 @@
-[build-system]
-requires = ["hatchling>=1.24"]
-build-backend = "hatchling.build"
-
-[project]
-name = "kache-ssh"
-version = "0.1.2"
-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"]
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kache-ssh"
+version = "0.2.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",
+    "segno>=1.5",
+]
+
+[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"]