cmux-ssh-here 0.5.0 → 0.6.0

package/README.md

@@ -1,46 +1,75 @@
 # cmux-ssh-here
 
-One command spins up an ephemeral, token-authenticated SSH server on this machine and prints a [cmux SSH deep link](https://cmux.com/en/docs/ssh). Open the link in [cmux](https://cmux.com) and you instantly land in a shell as the current user over the local network — no `sshd` setup, no keys, no passwords.
+**Share a shell on this machine in one command — no SSH setup, no keys, no passwords.**
+
+[![npm](https://img.shields.io/npm/v/cmux-ssh-here.svg)](https://www.npmjs.com/package/cmux-ssh-here)
+[![CI](https://github.com/viktor-silakov/cmux-ssh-here/actions/workflows/ci.yml/badge.svg)](https://github.com/viktor-silakov/cmux-ssh-here/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/cmux-ssh-here.svg)](./LICENSE)
+
+`cmux-ssh-here` spins up a throwaway, token-authenticated SSH server and prints a [cmux](https://cmux.com) deep link. Send the link to any device on your LAN, open it in cmux, and you're instantly in a terminal on this machine. When you're done, hit `Ctrl-C` — the server, token, and host key vanish.
 
 ```bash
 npx cmux-ssh-here
 ```
 
-Output:
+That's it. No `sshd` to configure, no `~/.ssh/authorized_keys` to edit, no firewall dance.
 
-```
-  Connect to this machine via cmux over the LAN
-  (shell as you; Ctrl-C here to stop):
+---
 
-  https://cmux.com/deeplink/ssh?host=192.168.1.42&port=52968&user=wudUKicRFRw3&host-key-policy=accept-new&title=your-mac
-```
+The terminal turns into a live dashboard — the link, a countdown bar for its lifetime, and who's connected:
+
+![cmux-ssh-here dashboard](https://raw.githubusercontent.com/viktor-silakov/cmux-ssh-here/main/assets/dashboard.png)
+
+Open the link and cmux connects on its own — one click, straight into the shell:
+
+![Open in cmux](https://raw.githubusercontent.com/viktor-silakov/cmux-ssh-here/main/assets/open-in-cmux.png)
+
+## Why you'll like it
 
-Open the link — cmux connects on its own. The server terminal shows a live dashboard: the current link, a countdown until it regenerates, and the list of connected sessions. `Ctrl-C` stops the server.
+- ⚡ **Zero setup** — one `npx` command, no SSH server administration.
+- 🔑 **No credentials to share** — auth is a one-time token baked into the link.
+- ⏳ **Self-expiring** — the link rotates every 3 minutes; leaked links go stale on their own. Live sessions stay connected.
+- 👀 **Live dashboard** — see the current link, a countdown bar, and every connected client at a glance.
+- 🧩 **Real SSH** — full PTY shell, `scp`/`sftp`, and the exec channel cmux needs to bootstrap remote workspaces.
+- 🪟 **Persistent sessions** — when `tmux` is present, sessions survive disconnects and are shared across connections.
 
-The link (and its token) is valid for **3 minutes**, then a fresh one is generated — already-connected sessions stay alive; only new connections need the new link.
+## Quick start
+
+```bash
+# on the machine you want to reach
+npx cmux-ssh-here
+```
+
+Then open the printed `https://cmux.com/deeplink/ssh?…` link in cmux on any device on the same network.
 
 ## How it works
 
 - Its own SSH server (`ssh2`) with an ephemeral host key and token — both live only while the process runs.
-- The token is passed in the deep link's `user=`; the server only accepts the correct token.
+- The token rides in the deep link's `user=`; the server accepts only that token, and rotates it every 3 minutes.
 - cmux deep links deliberately carry no passwords or keys, so the secret is the token itself.
-- Full PTY shell via `node-pty`, with window-resize support.
-- Real exec channel (raw pipes) and a filesystem-backed SFTP server, so `scp`/`sftp` work — this is what lets `cmux ssh` upload and run its remote helper. A shell-only server is not enough for cmux.
-- When `tmux` is available, the interactive shell runs inside it: sessions persist and are shared across connections, and the session list (`choose-tree`) is shown on connect. Without `tmux`, it falls back to a plain login shell.
+- Full PTY shell via `node-pty`, a raw-pipe exec channel, and a filesystem-backed SFTP server — together they let `cmux ssh` upload and run its remote helper (a shell-only server isn't enough).
+- With `tmux` available, the interactive shell runs inside it: sessions persist, are shared across connections, and the session list (`choose-tree`) is shown on connect.
+
+## Compatibility
 
-## Requirements
+| Host running `npx cmux-ssh-here` | Supported |
+| --- | --- |
+| macOS | ✅ |
+| Linux | ✅ |
+| Windows | ❌ — needs a POSIX shell, and cmux's remote daemon has no Windows build |
 
-- Node 18+.
-- [cmux](https://cmux.com) on the device you open the link from.
-- macOS or Linux on the host sharing the shell. Windows host is not supported.
-- `tmux` (optional) for persistent, shared server-side sessions.
+The device you open the link from just needs [cmux](https://cmux.com) installed. Node 18+ is required on the host. `tmux` is optional (for persistent, shared sessions).
 
 ## Security
 
-⚠️ **The token in the link is a bearer secret that grants a shell as your user.** Trusted local network only. Don't publish the link or send it over untrusted channels. Close the terminal and the token and host key are gone.
+⚠️ **The token in the link is a bearer secret that grants a shell as your user.** Use it on a trusted local network only. Don't publish the link or send it over untrusted channels. Close the terminal and the token and host key are gone.
 
 ## Options
 
 - `PORT=2222 npx cmux-ssh-here` — fixed port (random free port by default).
 - `CMUX_SSH_TTL=600 npx cmux-ssh-here` — link/token lifetime in seconds before regeneration (default 180).
 - `CMUX_SSH_DEBUG=1 npx cmux-ssh-here` — log incoming auth/env/exec/shell requests to stderr (disables the live dashboard).
+
+## License
+
+MIT

package/bin.js

@@ -19,6 +19,14 @@ import { chmodSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 
+// ponytail: the host side needs a POSIX shell + scp/exec semantics, and cmux's
+// own remote daemon only ships linux/darwin/freebsd builds — so a Windows host
+// can't serve `cmux ssh`. Fail fast with a clear message instead of crashing later.
+if (process.platform === "win32") {
+  console.error("cmux-ssh-here must run on a macOS or Linux host (POSIX shell required). Windows is not supported.");
+  process.exit(1);
+}
+
 // ponytail: node-pty's prebuilt spawn-helper sometimes unpacks without +x
 // (packaging bug) -> "posix_spawnp failed". Fix it before importing.
 if (process.platform !== "win32") {
@@ -50,7 +58,9 @@ const { privateKey } = generateKeyPairSync("rsa", {
   publicKeyEncoding: { type: "spki", format: "pem" },
 });
 
-const shellPath = process.env.SHELL || "/bin/zsh";
+// ponytail: $SHELL is set on real logins; the fallback only matters in bare
+// envs — bash on Linux, zsh on macOS.
+const shellPath = process.env.SHELL || (process.platform === "darwin" ? "/bin/zsh" : "/bin/bash");
 const debug = process.env.CMUX_SSH_DEBUG ? (...a) => console.error("[debug]", ...a) : () => {};
 
 const lanIP = () =>

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "cmux-ssh-here",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Spin up a token-auth SSH server and print a cmux deep link to connect over LAN",
   "type": "module",
   "bin": {
     "cmux-ssh-here": "bin.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "bin.js",
     "README.md"