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

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.

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.

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.

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.

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

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 for validation and release status.

MIT · Simon Malm.