Metadata-Version: 2.5
Name: kache-ssh
Version: 0.4.0
Summary: Kache: a desktop and multi-agent orchestration platform for your paired devices over SSH.
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: pillow>=10.4
Requires-Dist: platformdirs>=4.0
Requires-Dist: psutil>=5.9
Requires-Dist: pystray>=0.19.5
Requires-Dist: regex>=2024.11.6
Requires-Dist: textual>=8.0
Provides-Extra: desktop
Requires-Dist: pillow>=10.4; extra == 'desktop'
Requires-Dist: pystray>=0.19.5; extra == 'desktop'
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

A standalone desktop window, CLI and MCP server for working on your own paired
devices over SSH. Each device runs a **proxy**; commands, ownership and results
are visible in its activity feed.

## Install and open

```console
python -m pip install -U kache-ssh
kache
```

The desktop has device and shell selectors, a terminal, activity, active actors
and addressed chat. PowerShell, Bash, cmd and Zsh commands run in that exact
installed interpreter, without translation. Closing hides the window in the tray;
the dot icon opens it and its menu shows addresses and Exit.
`kache tui` retains the previous Textual interface.

Python 3.10+ is required. Windows Python needs its bundled Tcl/Tk for the window.
Headless machines can use CLI, MCP and proxy without opening a window.
Opening the desktop starts the proxy if needed; startup registration is explicit:
`kache service install`.

## Pair your own devices

Open Kache on both devices. Run `kache pair ADDRESS`; compare the six-digit
code on both screens and accept on the receiving device. Pairing grants broad
access as the proxy's OS user, not an agent sandbox. Clients offer only Kache's
device key and verify the destination's pinned fingerprint.

```console
kache devices --json
kache run desktop --as codex --actor-id project-a --shell powershell --timeout 30 -- Get-Location
kache run desktop --as codex --detach -- python train.py
kache jobs --json
kache logs J-abc123 -d desktop
```

Foreground sessions retain variables, cwd and activated environments. The proxy
limits them to 32 and expires idle sessions after 30 minutes. Cancellation resets
a busy shell. Detached jobs survive disconnection and proxy restart.

## Working together

`kache actors --json` lists active actors, home devices and work across reachable
paired devices. Use KACHE_AS and a distinct stable KACHE_ACTOR for each CLI agent.
MCP instances have distinct ids. Labels are attribution, not security boundaries.

Starting work on an occupied device returns its owner/task and a generation token.
Decide whether to proceed, then retry with `--acknowledge TOKEN`. New work
invalidates old acknowledgements.

```console
kache chat @alice "Please inspect the test report" -d desktop --as bob
kache inbox -d desktop --as alice --json
```

Unread messages stop an agent's next command/job for review and are shown once.
This **does not wake an idle AI or guarantee a reply**. Delivery is at-most-once;
history remains after a lost response. Offline proxies retain mail.

## Platform tools

- Shell-free ls/cat/tail/find/ps/top/gpu/disk/inventory.
- Hash-checked patch, backups and stale-safe undo.
- Incremental `sync SOURCE DEVICE:FOLDER`, optional --watch, per-file atomic
  staged commits, no remote deletion.
- Direct `copy SOURCE_DEVICE:PATH DEST_DEVICE:PATH`, using an existing pairing
  from source to destination. No payload relay through the controller.
- Bounded waits for files, log regexes, jobs and ports.
- Explicit supervised services and interval/daily schedules. Operator stops persist.
- Line-oriented job stdin, including EOF; not a full PTY.
- LAN Wake-on-LAN, interactive-desktop screenshots, seven-day health history.
- Best-effort OpenSSH successful-login visibility, without elevation or audit edits.

Full commands, schemas and limitations: `kache guide` or
[src/kache/AGENTS.md](src/kache/AGENTS.md).

## Updates and compatibility

0.4 uses **protocol 2 / JSON schema 2**. Update both endpoints. Historical feeds,
job files and identities are retained. Gatekeeper/run_order source aliases remain;
the preferred names are Proxy/run_command.

```console
kache update all --to-version 0.4.0 --confirm
```

Updates stage a pinned package in a separate environment, verify imports, activate
remotes before the controller, and check the same pinned key/version. Previous
environments and jobs remain. Managed activation supports Windows login proxies;
privileged boot tasks need explicit operator updates. Do not delete environments
while old jobs use them.

## MCP and development

```console
kache mcp
python -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"
.venv/Scripts/python -m pytest -q
```

Existing MCP tools remain, plus kache_tool for structured operations. Long-lived
MCP and desktop clients reuse pinned connections without retrying commands.
`kache_screenshot` returns an actual PNG image content block to MCP clients.

Tests use temporary identities and loopback proxies, not production startup,
pairing, hardware or training. See [IMPLEMENTATION.md](IMPLEMENTATION.md) for
validation and release status.

MIT · Simon Malm.
