@akms/mcp-ssh 0.0.1 → 0.0.2

package/README.md

@@ -1,332 +1,191 @@
-# @akms/ssh-mcp
-
-> 🔒 Internal use only — built for our organization's services.
-
-MCP server that lets an AI agent run shell commands and transfer files on remote hosts over SSH.
-
-Hosts are **pre-registered in a local config file**; the agent picks one by alias and never receives a hostname, key or password as an argument. Every command and path is screened against the profile's guard policy before anything reaches the network.
-
-## 📦 Installation
-
-```bash
-npm install -g @akms/ssh-mcp   # installs the `akms-ssh` command
-akms-ssh --help
-
-# or run it straight from the registry, no install
-npx -y @akms/ssh-mcp --help
-```
-
-## ⚙️ MCP client setup
-
-**One server entry per host.** Each entry is plain `SSH_*` variables — no config file, no JSON inside JSON.
-
-Claude Code — `.mcp.json` in the project, or `~/.claude.json` for every project:
-
-```json
-{
-    "mcpServers": {
-        "ssh-dev": {
-            "command": "npx",
-            "args": ["-y", "@akms/ssh-mcp"],
-            "env": {
-                "SSH_HOST": "192.168.0.10",
-                "SSH_USER": "ubuntu",
-                "SSH_KEY": "~/.ssh/id_ed25519"
-            }
-        },
-        "ssh-prod": {
-            "command": "npx",
-            "args": ["-y", "@akms/ssh-mcp"],
-            "env": {
-                "SSH_HOST": "10.0.0.5",
-                "SSH_USER": "deploy",
-                "SSH_KEY": "~/.ssh/id_ed25519",
-                "SSH_READONLY": "true",
-                "SSH_ALLOW_SUDO": "false",
-                "SSH_ALLOWED_PATHS": "/var/log,/opt/app"
-            }
-        }
-    }
-}
-```
-
-`SSH_HOST` + `SSH_USER` is the whole minimum. The **private key stays a file on disk** — only its path goes in the config.
-
-Because each server fronts one host, the agent never names it: `ssh_exec({ command: "df -h" })` is a complete call. The server name (`ssh-dev`, `ssh-prod`) is what the agent sees in its tool list, so name it after the host.
-
-Claude Desktop — same block inside `claude_desktop_config.json`.
-
-The server speaks MCP over **stdio**: stdout carries the JSON-RPC stream and all logging goes to stderr. Running it by hand in a terminal only prints the startup line and waits.
-
-## 🗂️ Host configuration
-
-### One host per server — `SSH_*` variables
-
-| Variable | | |
-|---|---|---|
-| `SSH_HOST` | ✅ | Hostname or IP. Its presence selects single-host mode |
-| `SSH_USER` | ✅ | Login user |
-| `SSH_PORT` | | Default `22` |
-| `SSH_KEY` | | Path to a private key file, `~` expanded |
-| `SSH_PASSPHRASE` / `SSH_PASSWORD` | | Key passphrase / password auth |
-| `SSH_HOST_KEY` | | Pin the server's host key, `SHA256:…` |
-| `SSH_NAME` | | Profile alias; defaults to the hostname |
-| `SSH_DESCRIPTION` | | Shown to the agent — say what the host is for |
-| `SSH_CWD` | | Directory new sessions start in |
-| `SSH_READONLY` | | `true` / `false` (also `1`/`0`, `yes`/`no`, `on`/`off`) |
-| `SSH_ALLOW_SUDO` | | Default `true` |
-| `SSH_ALLOW_COMMANDS` | | Comma-separated allow-list, e.g. `ls,cat,tail` |
-| `SSH_DENY_PATTERNS` | | Comma-separated regex sources |
-| `SSH_ALLOWED_PATHS` | | Comma-separated path prefixes for the file tools |
-| `SSH_EXEC_TIMEOUT_MS` / `SSH_CONNECT_TIMEOUT_MS` | | Timeouts in ms |
-| `SSH_MAX_OUTPUT` / `SSH_MAX_READ_BYTES` | | Output and read ceilings |
-
-A malformed value fails startup rather than being ignored — `SSH_READONLY=ture` is an error, not "not read-only".
-
-Regexes containing a comma need the JSON form below.
-
-### Several hosts in one server — `SSH_MCP_CONFIG`
-
-For the case where one entry really should front several hosts. Resolution order overall:
-
-1. `--config <path>` CLI flag
-2. `SSH_HOST` — single host from the variables above
-3. `SSH_MCP_CONFIG` — **the JSON itself** if the value starts with `{`, otherwise a path to a JSON file
-4. `~/.akms-ssh.json`
-5. `~/.config/akms-ssh/config.json`
-
-A JSON object always starts with `{` and a filesystem path never does, so one variable covers both without ambiguity. With several hosts registered, tools take a `target` argument naming one.
-
-This is the shape, whether inline or in a file:
-
-```json
-{
-    "defaults": { "execTimeoutMs": 120000 },
-    "hosts": {
-        "dev-box": {
-            "host": "192.168.0.10",
-            "username": "ubuntu",
-            "privateKeyPath": "~/.ssh/id_ed25519"
-        },
-        "prod-web": {
-            "host": "10.0.0.5",
-            "username": "deploy",
-            "privateKeyPath": "~/.ssh/id_ed25519",
-            "passphraseEnv": "PROD_WEB_KEY_PASSPHRASE",
-            "readonly": true,
-            "allowSudo": false,
-            "allowedPaths": ["/var/log", "/opt/app"]
-        }
-    }
-}
-```
-
-A missing config is not fatal — the server starts with zero profiles and the tools say so. A config that **exists but is malformed** aborts startup, so a typo in a policy field can never silently drop a guard.
-
-That includes *unknown* keys: `readOnly` (capital O) is rejected rather than ignored. A schema that silently dropped it would leave a host you believed was read-only fully writable.
-
-**Inline or file?** Inline keeps everything in one place and travels with the MCP config. A file is easier to read and edit, and can be `chmod 600` — the server warns if it is group/world readable.
-
-### Check it before wiring it up
-
-```bash
-akms-ssh --check              # or: npx -y @akms/ssh-mcp --check
-```
-
-Connects to every profile and reports what happened — exit code 0 when all are reachable:
-
-```
-Checking 3 profile(s) from inline SSH_MCP_CONFIG
-
-  OK      dev-box   →  ubuntu@192.168.0.10:22  (key ~/.ssh/id_ed25519, 412ms)
-          host key SHA256:9x2K…  (not pinned — add it as hostKeyFingerprint to detect a changed key)
-  FAILED  prod-web  →  deploy@10.0.0.5:22  (key /home/me/.ssh/id_ed25519)
-          All configured authentication methods failed
-
-1 of 2 reachable
-```
-
-Without this the only way to test a config is to ask the agent to try something, which confuses a setup mistake with a policy rejection. Add `SSH_MCP_LOG_LEVEL=debug` to see the handshake.
-
-### Host key pinning
-
-The fingerprint printed above is the same string `ssh-keyscan -t ed25519 host | ssh-keygen -lf -` gives. Copy it into the profile to pin it:
-
-```json
-"prod-web": { "host": "10.0.0.5", "username": "deploy", "hostKeyFingerprint": "SHA256:9x2K…" }
-```
-
-A mismatch then aborts the connection. **Unpinned profiles accept whatever key the server presents** — fine on a LAN, worth pinning across the internet, and the thing that tells you a host was rebuilt.
-
-### Connection fields
-
-| Field | Required | Description |
-|---|---|---|
-| `host` | ✅ | Hostname or IP |
-| `username` | ✅ | Login user |
-| `port` | | Default `22` |
-| `description` | | Shown in `ssh_list_hosts`; tell the agent what the host is for |
-| `defaultCwd` | | Directory new sessions start in |
-| `privateKeyPath` | | **Path** to a private key file, `~` expanded — the usual choice |
-| `privateKey` | | Key contents, for the rare case where no file exists |
-| `passphrase` / `passphraseEnv` | | Key passphrase, inline or from an env var |
-| `password` / `passwordEnv` | | Password auth, inline or from an env var |
-| `hostKeyFingerprint` | | Pin the server's host key, e.g. `SHA256:9x2K…`; a mismatch aborts the connection |
-
-Three ways to authenticate, tried in this order:
-
-1. **Private key by path** — `"privateKeyPath": "~/.ssh/id_ed25519"`, with `passphraseEnv` if the key is encrypted. The key never enters the config; only its path does. A path that doesn't exist is reported at startup rather than at first connection.
-2. **Password** — `"passwordEnv": "PROD_PASSWORD"` keeps it out of the JSON.
-3. **SSH agent** — used automatically when neither key nor password is set (`SSH_AUTH_SOCK`, or the OpenSSH named pipe on Windows).
-
-`*Env` variants are preferred: the secret stays in your shell or keychain. When the named variable is empty the inline value is used and a warning is logged.
-
-### Policy fields
-
-Settable in `defaults` (file-wide) and per host. Resolution order: **built-in → `defaults` → host override**.
-
-| Field | Default | Effect |
-|---|---|---|
-| `readonly` | `false` | Rejects write commands, output redirection, package installs, uploads and remote writes |
-| `allowSudo` | `true` | When false, rejects `sudo` / `su` / `doas` / `pkexec` / `runuser` / `chroot` |
-| `allowCommands` | `[]` | When non-empty, only these binaries may run — the strictest lever available (`pwd` is added automatically so sessions can open) |
-| `denyPatterns` | `[]` | Extra regex sources, compiled at startup and tested per command segment |
-| `allowedPaths` | `[]` | When non-empty, the file tools accept only absolute paths inside these prefixes |
-| `execTimeoutMs` | `60000` | Per-command wall clock; the channel is closed when it elapses |
-| `connectTimeoutMs` | `20000` | TCP + handshake limit |
-| `maxOutputCharacters` | `100000` | stdout and stderr are each truncated past this |
-| `maxReadFileBytes` | `200000` | `ssh_read_file` ceiling |
-
-**Defaults are permissive on purpose.** An unconfigured host allows ordinary administration — installs, service restarts, sudo, interpreters, deployments — because a guard that blocks real work gets switched off wholesale instead of tuned. Restriction is opt-in, per host.
-
-An explicitly empty array (`"allowCommands": []`) on a host *overrides* a restrictive `defaults` block and is warned about at startup, since "nothing extra" and "no restriction" are opposite readings of the same syntax.
-
-## 🧰 Tools
-
-| Tool | Purpose |
-|---|---|
-| `ssh_list_hosts` | Registered profiles with each one's guard policy. No credentials |
-| `ssh_reload_config` | Re-read the config after you edit it, without restarting the client |
-| `ssh_connect` | Open a reusable session, returns a session id |
-| `ssh_disconnect` | Close a session |
-| `ssh_list_sessions` | Open sessions with cwd, command count and idle time |
-| `ssh_exec` | Run a command; returns stdout, stderr, exit code, duration |
-| `ssh_list_dir` | SFTP directory listing (type, mode, size, mtime) |
-| `ssh_read_file` | Read a remote text file, truncated to the byte ceiling |
-| `ssh_write_file` | Write or append UTF-8 text over SFTP |
-| `ssh_upload` | Local → remote file transfer |
-| `ssh_download` | Remote → local file transfer |
-
-### Naming the host
-
-With a single configured host — the intended setup — `target` is omitted entirely and every tool uses that host. It becomes required only when a server fronts several, and the error then lists them.
-
-### One-off vs session
-
-Every operation tool takes **either** `target` (a profile alias) **or** `session` (an id from `ssh_connect`) — passing both is an error, since they can name different hosts under different policies:
-
-- `target` — a fresh connection is opened and closed around the single call. Simple, but pays a handshake each time and keeps no state. Capped at 16 concurrent.
-- `session` — reuses the connection and **remembers the working directory**, so `cd /opt/app` in one `ssh_exec` still applies to the next. Passing `cwd` alongside `session` moves the session there.
-
-Sessions are capped at 32 and reaped after 15 minutes idle — but never while an operation is running, so a long build or a large transfer is safe.
-
-If the connection drops, the session says so on the next call instead of silently reconnecting. A reconnect would hand back a fresh login shell — environment variables, sudo cache and background jobs gone — while the model still believed it held the old one.
-
-### Exit codes are not errors
-
-A non-zero exit code comes back as ordinary output with stdout and stderr — the agent reads it and decides. Only a genuine failure (unknown profile, connection refused, guard rejection) is flagged as a tool error.
-
-### Commands run without a terminal
-
-Remote stdin is closed immediately, so anything that waits for input fails fast instead of hanging until the timeout:
-
-- `sudo` on a host without `NOPASSWD` fails with `sudo: a password is required` in milliseconds. Either configure `NOPASSWD` for the commands the agent needs, or use `sudo -n` and expect the failure.
-- Confirmation prompts need their non-interactive flag — `apt-get install -y`, `rm -f`, `ssh-keygen -q -N ''`.
-- Full-screen tools (`top`, `vi`, `htop`) have no TTY. Use `top -bn1`, `ps aux`, and `ssh_write_file` instead of an editor.
-
-A long job outliving its timeout keeps running remotely; start it with `nohup … &` or `tmux new -d` and poll the log.
-
-## 🛡️ Guard policy
-
-**The threat model is a mistaken agent, not an adversary.** An agent that means well can still type `rm -rf /` with a variable that expanded to nothing, or reboot the host it is currently working through. Those are what the guards stop. An agent — or a prompt injection — that is *trying* to get around a text-based screen will succeed, because a shell can express the same operation in unlimited ways. Chasing that is how a guard ends up blocking `awk` and getting turned off.
-
-So the layers are:
-
-| Layer | Scope | Examples |
-|---|---|---|
-| **Catastrophe** | Every profile, not configurable | `rm -rf /` (and `/etc`, `/home`, `~`, `//*`, `/tmp/x /`), `rm /etc/passwd`, `rm /boot/vmlinuz*`, `mkfs`, `dd of=/dev/sda`, `shutdown`, `reboot`, `chmod -R 777 /`, `find / -delete`, `crontab -r`, `iptables -F`, `--no-preserve-root`, fork bombs |
-| `readonly` | Opt-in per profile | `rm`/`mv`/`cp`/`mkdir`/`tee`, package installs, editors, `ssh`/`scp`/`wget`, `sed -i`, `sort -o`, `find -delete`, `git push`, `systemctl restart`, `docker run`, `kubectl apply`, `tar -x`, `curl -o`, `> file` redirection |
-| `allowSudo: false` | Opt-in per profile | any segment invoking `sudo`, `su`, `doas`, `pkexec`, `runuser`, `chroot` |
-| `allowCommands` / `denyPatterns` | Opt-in per profile | whatever you list |
-| Path guards | `allowedPaths` (remote), built-in credential rules (local) | paths outside the allow-list; local credential and config files |
-| `cwd` | Every profile | a working directory containing shell metacharacters |
-
-Everything not in that table runs. Installing packages, restarting services, editing configs, `curl … \| sh`, deleting an application's own files, `sudo` — all ordinary work, all allowed by default.
-
-### What `readonly` deliberately allows
-
-Interpreters (`python3 -c`, `node -e`, `perl -ne`), `awk`, database clients, `git log`, `docker logs`, `tar -tzf`. A read-only host exists to be **inspected**, and log analysis needs those. Blocking them made the mode unusable for its own purpose while stopping nobody — a shell payload is still screened, so `bash -c "rm x"` is caught by the `rm` rule.
-
-### How a command is screened
-
-1. **Canonicalize** — `\`+newline continuations are removed (as POSIX does) and <code>$&#123;IFS&#125;</code> expands to a space. The canonical text is what gets screened **and** what gets sent; validating one string and running another is a bypass by construction.
-2. **Pipeline rules** — fork bombs.
-3. **Nested commands** — `$(…)`, backticks and process substitution `<(…)` are each screened as their own command, recursively.
-4. **Split into segments** on `;`, `&&`, `||`, `|`, `&` and newlines. Quoted text stays intact, so `echo "a; b"` is one segment.
-5. **Per segment**, the binary that actually runs is resolved by stepping past `FOO=bar` assignments, redirection tokens, shell keywords (`if`, `then`, `{`, `(`), wrapper binaries (`sudo`, `env`, `nohup`, `timeout`, `eval`, `busybox`, …), their numeric operands and their flag values — so `timeout 30 sudo rm -rf /` resolves to `rm`, not `30`, and `env -u PATH rm -rf /` resolves to `rm`, not `PATH`. The binary is reduced to its basename, so `/sbin/reboot` matches the same rule as `reboot`.
-6. **Nested payloads** — a `-c "…"` string (including bundled forms like `bash -lc`) or a `--` argv tail is screened as its own command.
-
-Every rule is enforced inside `SshConnection.exec` and the SFTP operations — the layer every command and path must pass through — so a new tool cannot forget to call the guard.
-
-A rejection returns the rule that fired, the offending segment, and the note that nothing was sent.
-
-`allowedPaths` binds the **file tools only**. `ssh_exec` can still read anything the remote account can — `ssh_list_hosts` says so on each profile.
-
-`timeoutMs` and `maxBytes` are **clamps, not defaults**: a per-call value may lower the profile's ceiling, never raise it.
-
-### The real boundary is the remote account
-
-Since the guards are a mistake-stopper, containment has to come from the host:
-
-- give each profile a **dedicated unprivileged user**, not `root`
-- restrict that user's `sudoers` entries to the exact commands it needs
-- pair `readonly: true` with filesystem permissions that agree with it
-- for the strictest hosts use `allowCommands` — an allow-list beats any deny-list
-- snapshot or back up anything you would miss
-
-### Local path protection
-
-The file tools run with this server's own privileges on your machine, so `localPath` is guarded in both directions — but narrowly, covering two things only:
-
-- **Credentials**: `~/.ssh`, `authorized_keys`, private keys, `.pem`/`.key`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.docker`, `.npmrc`, `.netrc`
-- **Files that define the guards**: this server's config, `.claude*` / `.mcp.json` / `claude_desktop_config.json`, and autostart locations
-
-`.env` uploads, `.bashrc` backups and cron fetches are normal deployment work and are allowed. Symlinks are resolved before matching, so a link into `~/.ssh` does not slip past.
-
-## 📄 Logging
-
-Everything goes to **stderr** (stdout is the MCP protocol channel).
-
-| Variable | Description | Default |
-|---|---|---|
-| `SSH_MCP_CONFIG` | Host profiles as JSON (value starts with `{`), or a path to a JSON file | `~/.akms-ssh.json` |
-| `SSH_MCP_LOG_LEVEL` | `silent` / `debug` / `info` / `warn` / `error` | `info` |
-
-Guard rejections are logged at `warn` with the full command — that log is the audit trail for what the agent tried. Full command text is otherwise only logged at `debug`; `password`, `passphrase`, `privateKey` and `token` meta keys are always masked.
-
-## ⚠️ Security notes
-
-- The config names hosts and may hold passwords. Inline in an MCP config means that file now carries them — treat `.mcp.json` accordingly, and prefer `passwordEnv` / `passphraseEnv` so only the *name* of a variable is stored. A config file should be `chmod 600` and never committed; the shipped `.gitignore` already excludes `.akms-ssh.json`, `*.pem`, `id_rsa*` and `id_ed25519*`.
-- **Anything the agent can reach, a prompt injection can reach.** Output from a remote host is untrusted input; a file the agent reads can contain instructions. With permissive defaults that matters more, not less — keep production profiles `readonly` and let write access be a deliberate exception.
-- The catastrophe rules are the *only* ones that hold on every profile, and even they read the command as text. Treat them as a seatbelt, not a cage.
-- Point profiles at hosts you are authorized to administer. This is an administration tool, not a scanner.
-- Local paths are resolved against the machine running the server, so on Windows a POSIX-looking `/tmp/x` becomes `<current drive>\tmp\x`. Every transfer reply prints the resolved path — check it.
-- `timeoutMs` closes the local channel; the remote process may keep running. For long jobs use `nohup`/`tmux` and poll.
-
-## 🧑‍💻 Development
-
-Building on this server, embedding it as a library, or changing the guards — see [README_DEV.md](README_DEV.md).
-
-## 📜 License
-
-MIT — see [LICENSE.md](LICENSE.md).
+# @akms/mcp-ssh
+
+> 🔒 Internal use only — built for our organization's services.
+
+MCP server that lets an AI agent run shell commands and transfer files on a remote host over SSH.
+
+The host is **pre-registered** in the server's own environment; the agent never receives a hostname, key or password as an argument, and no tool takes one. Every command and path is screened against the guard policy before anything reaches the network.
+
+## 📦 Installation
+
+```bash
+npm install -g @akms/mcp-ssh   # installs the `akms-mcp-ssh` command
+npx -y @akms/mcp-ssh --help    # or run it straight from the registry
+```
+
+## ⚙️ MCP client setup
+
+**One server entry per host** — plain `SSH_*` variables, no config file, no JSON inside JSON. Claude Code reads `.mcp.json` in the project or `~/.claude.json` globally; Claude Desktop takes the same block inside `claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "ssh-prod": {
+            "command": "npx",
+            "args": ["-y", "@akms/mcp-ssh"],
+            "env": {
+                "SSH_HOST": "10.0.0.5", "SSH_USER": "deploy", "SSH_KEY": "~/.ssh/id_ed25519",
+                "SSH_READONLY": "true", "SSH_ALLOWED_PATHS": "/var/log,/opt/app"
+            }
+        }
+    }
+}
+```
+
+`SSH_HOST` + `SSH_USER` is the whole minimum, and the **private key stays a file on disk** — only its path goes in the config. Because each server fronts one host, the agent never names it: `ssh_exec({ command: "df -h" })` is a complete call. The server name (`ssh-prod`) is what the agent sees in its tool list, so name it after the host.
+
+The server speaks MCP over **stdio**: stdout carries the JSON-RPC stream and all logging goes to stderr. Running it by hand in a terminal only prints the startup line and waits.
+
+## 🗂️ Host configuration
+
+Every setting is an environment variable in this server's own entry. There is no config file and no JSON — which is also why "what is this server allowed to do" is answerable by reading the entry above, with no second place to check.
+
+### Connection
+
+| `SSH_*` variable | Description |
+|---|---|
+| `SSH_HOST` ✅ | Hostname or IP |
+| `SSH_USER` ✅ | Login user |
+| `SSH_PORT` | Default `22` |
+| `SSH_KEY` | **Path** to a private key file, `~` expanded |
+| `SSH_PASSPHRASE` | Key passphrase |
+| `SSH_PASSWORD` | Password auth, when no key is used |
+| `SSH_HOST_KEY` | Pin the server's host key, `SHA256:…`; a mismatch aborts the connection |
+| `SSH_NAME` | Alias shown to the agent; defaults to the hostname |
+| `SSH_DESCRIPTION` | Shown to the agent — say what the host is for |
+| `SSH_CWD` | Directory new sessions start in |
+
+Authentication is tried in this order: **private key by path** (with `SSH_PASSPHRASE` if encrypted), **password**, then the **SSH agent** when neither is set (`SSH_AUTH_SOCK`, or the OpenSSH named pipe on Windows). A key path that doesn't exist is reported at startup, not at first connection.
+
+### Policy
+
+| `SSH_*` variable | Default | Effect |
+|---|---|---|
+| `SSH_READONLY` | `false` | Rejects write commands, output redirection, package installs, uploads and remote writes |
+| `SSH_ALLOW_SUDO` | `true` | When false, rejects `sudo` / `su` / `doas` / `pkexec` / `runuser` / `chroot` |
+| `SSH_ALLOW_COMMANDS` | *(none)* | When set, only these binaries may run — the strictest lever available (`pwd` is added automatically so sessions can open) |
+| `SSH_DENY_PATTERNS` | *(none)* | Extra regex sources, compiled at startup and tested per command segment |
+| `SSH_ALLOWED_PATHS` | *(none)* | When set, the file tools accept only absolute paths inside these prefixes |
+| `SSH_EXEC_TIMEOUT_MS` | `60000` | Per-command wall clock; the channel is closed when it elapses |
+| `SSH_CONNECT_TIMEOUT_MS` | `20000` | TCP + handshake limit |
+| `SSH_MAX_OUTPUT` | `100000` | stdout and stderr are each truncated past this |
+| `SSH_MAX_READ_BYTES` | `200000` | `ssh_read_file` ceiling |
+
+**Defaults are permissive on purpose.** An unconfigured host allows ordinary administration — installs, service restarts, sudo, interpreters, deployments — because a guard that blocks real work gets switched off wholesale instead of tuned. Restriction is opt-in.
+
+Lists are comma-separated and booleans also accept `1`/`0`, `yes`/`no`, `on`/`off`. A malformed value fails startup rather than being ignored — `SSH_READONLY=ture` is an error, not "not read-only" — and `SSH_DENY_PATTERNS` is compiled at startup, so a typo'd regex can't be silently absent at the moment it matters. A missing `SSH_HOST` is not fatal: the server starts with nothing registered and the tools say so.
+
+### Several hosts
+
+Add a server entry per host. Each one carries its own connection and its own policy, right where you read it, and the agent picks a host by choosing a tool — there is no host argument to get wrong:
+
+```json
+{
+    "mcpServers": {
+        "ssh-prod": {
+            "command": "npx", "args": ["-y", "@akms/mcp-ssh"],
+            "env": { "SSH_HOST": "10.0.0.5", "SSH_USER": "deploy", "SSH_READONLY": "true" }
+        },
+        "ssh-dev": {
+            "command": "npx", "args": ["-y", "@akms/mcp-ssh"],
+            "env": { "SSH_HOST": "192.168.0.10", "SSH_USER": "ubuntu" }
+        }
+    }
+}
+```
+
+### Check it before wiring it up
+
+```bash
+akms-mcp-ssh --check          # or: npx -y @akms/mcp-ssh --check
+```
+
+Connects to the configured host and reports what happened — exit code 0 when it is reachable. Otherwise a setup mistake is indistinguishable from a policy rejection when the agent tries something. Add `SSH_MCP_LOG_LEVEL=debug` to see the handshake.
+
+```
+Checking prod-web  →  deploy@10.0.0.5:22
+
+  OK      deploy@10.0.0.5:22  (key /home/me/.ssh/id_ed25519, 412ms)
+          host key SHA256:9x2K…  (not pinned — set SSH_HOST_KEY to it to detect a changed key)
+```
+
+That fingerprint is the same string `ssh-keyscan -t ed25519 host | ssh-keygen -lf -` gives — copy it into `SSH_HOST_KEY` to pin it. **An unpinned host accepts whatever key the server presents**: fine on a LAN, worth pinning across the internet, and the thing that tells you a host was rebuilt.
+
+## 🧰 Tools
+
+| Tool | Purpose |
+|---|---|
+| `ssh_list_hosts` | The configured host and its guard policy. No credentials |
+| `ssh_connect` | Open a reusable session, returns a session id |
+| `ssh_disconnect` | Close a session |
+| `ssh_list_sessions` | Open sessions with cwd, command count and idle time |
+| `ssh_exec` | Run a command; returns stdout, stderr, exit code, duration |
+| `ssh_list_dir` | SFTP directory listing (type, mode, size, mtime) |
+| `ssh_read_file` | Read a remote text file, truncated to the byte ceiling |
+| `ssh_write_file` | Write or append UTF-8 text over SFTP |
+| `ssh_upload` | Local → remote file transfer |
+| `ssh_download` | Remote → local file transfer |
+
+### One-off vs session
+
+No tool takes a host argument — the host is the one in this server's env block, so the agent can't name a machine. The only choice is whether to reuse a connection:
+
+- **Omit `session`** — a fresh connection is opened and closed around the single call. Simple, but pays a handshake each time and keeps no state. Capped at 32 concurrent.
+- **Pass `session`** (an id from `ssh_connect`) — reuses the connection and **remembers the working directory**, so `cd /opt/app` in one `ssh_exec` still applies to the next. Passing `cwd` alongside `session` moves the session there. Capped at 32, reaped after 15 minutes idle but never mid-operation, so a long build or a large transfer is safe. A dropped connection is reported on the next call rather than silently reconnected into a fresh login shell.
+
+A non-zero exit code comes back as ordinary output with stdout and stderr for the agent to read; only a genuine failure (connection refused, guard rejection) is flagged as a tool error.
+
+### Commands run without a terminal
+
+Remote stdin is closed immediately, so anything that waits for input fails fast instead of hanging until the timeout:
+
+- `sudo` on a host without `NOPASSWD` fails with `sudo: a password is required` in milliseconds. Either configure `NOPASSWD` for the commands the agent needs, or use `sudo -n` and expect the failure.
+- Confirmation prompts need their non-interactive flag — `apt-get install -y`, `rm -f`, `ssh-keygen -q -N ''`.
+- Full-screen tools (`top`, `vi`, `htop`) have no TTY. Use `top -bn1`, `ps aux`, and `ssh_write_file` instead of an editor.
+
+A long job outliving its timeout keeps running remotely; start it with `nohup … &` or `tmux new -d` and poll the log.
+
+## 🛡️ Guard policy
+
+**The threat model is a mistaken agent, not an adversary.** An agent that means well can still type `rm -rf /` with a variable that expanded to nothing, or reboot the host it is currently working through. Those are what the guards stop. One that is *trying* to get around a text-based screen will succeed — a shell can express the same operation in unlimited ways, and chasing that is how a guard ends up blocking `awk` and getting turned off. So the layers are deliberately few:
+
+| Layer | Scope | Examples |
+|---|---|---|
+| **Catastrophe** | Always, not configurable | `rm -rf /` (and `/etc`, `/home`, `~`, `//*`, `/tmp/x /`), `rm /etc/passwd`, `rm /boot/vmlinuz*`, `mkfs`, `dd of=/dev/sda`, `shutdown`, `reboot`, `chmod -R 777 /`, `find / -delete`, `crontab -r`, `iptables -F`, `--no-preserve-root`, fork bombs |
+| `SSH_READONLY` | Opt-in | `rm`/`mv`/`cp`/`mkdir`/`tee`, package installs, editors, `ssh`/`scp`/`wget`, `sed -i`, `sort -o`, `find -delete`, `git push`, `systemctl restart`, `docker run`, `kubectl apply`, `tar -x`, `curl -o`, `> file` redirection |
+| `SSH_ALLOW_SUDO=false` | Opt-in | any segment invoking `sudo`, `su`, `doas`, `pkexec`, `runuser`, `chroot` |
+| `SSH_ALLOW_COMMANDS` / `SSH_DENY_PATTERNS` | Opt-in | whatever you list |
+| Path guards | `SSH_ALLOWED_PATHS` (remote), built-in credential rules (local) | paths outside the allow-list; local credential and config files |
+| `cwd` | Always | a working directory containing shell metacharacters |
+
+Everything not in that table runs: installing packages, restarting services, editing configs, `curl … | sh`, deleting an application's own files, `sudo`. `SSH_READONLY` deliberately still allows interpreters (`python3 -c`, `node -e`), `awk`, database clients, `git log`, `docker logs` — a read-only host exists to be **inspected**, and log analysis needs those. A shell payload is screened either way, so `bash -c "rm x"` is caught by the `rm` rule.
+
+Rules are enforced inside `SshConnection.exec` and the SFTP operations — the layer every command and path must pass through — so a new tool cannot forget to call the guard. A rejection returns the rule that fired, the offending segment, and the note that nothing was sent. The screening walkthrough is in [README_DEV.md](README_DEV.md#how-a-command-is-screened).
+
+`SSH_ALLOWED_PATHS` binds the **file tools only**: `ssh_exec` can still read anything the remote account can, and `ssh_list_hosts` says so. Per-call `timeoutMs` and `maxBytes` are **clamps, not defaults** — they may lower the configured ceiling, never raise it.
+
+### Local path protection
+
+The file tools run with this server's own privileges on your machine, so `localPath` is guarded in both directions — but narrowly, covering **credentials** (`~/.ssh`, `authorized_keys`, private keys, `.pem`/`.key`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.docker`, `.npmrc`, `.netrc`) and **files that define the guards** (`.claude*` / `.mcp.json` / `claude_desktop_config.json` — where this server's `SSH_*` variables live — plus autostart locations). `.env` uploads, `.bashrc` backups and cron fetches are normal deployment work and are allowed. Symlinks are resolved before matching, so a link into `~/.ssh` does not slip past.
+
+## 📄 Logging
+
+Everything goes to **stderr** (stdout is the MCP protocol channel). `SSH_MCP_LOG_LEVEL` picks the level — `silent` / `debug` / `info` / `warn` / `error`, default `info`. Guard rejections are logged at `warn` with the full command, and that log is the audit trail for what the agent tried; full command text is otherwise only logged at `debug`, while `password`, `passphrase`, `privateKey` and `token` meta keys are always masked.
+
+## ⚠️ Security notes
+
+**The real boundary is the remote account.** The guards stop mistakes; containment has to come from the host — give each server entry a dedicated unprivileged user rather than `root`, restrict its `sudoers` entries to the exact commands it needs, pair `SSH_READONLY=true` with filesystem permissions that agree with it, reach for `SSH_ALLOW_COMMANDS` on the strictest hosts, and back up anything you would miss.
+
+- The MCP client entry names the host and may hold `SSH_PASSWORD` or `SSH_PASSPHRASE`. Prefer a key file so only its *path* is stored, keep the entry out of version control, and `chmod 600` it — the shipped `.gitignore` already excludes `*.pem`, `id_rsa*` and `id_ed25519*`.
+- **Anything the agent can reach, a prompt injection can reach.** Output from a remote host is untrusted input; a file the agent reads can contain instructions. With permissive defaults that matters more, not less — keep a production entry `SSH_READONLY=true` and let write access be a deliberate exception.
+- The catastrophe rules are the *only* ones that hold regardless of configuration, and even they read the command as text. Treat them as a seatbelt, not a cage.
+- Point this at hosts you are authorized to administer. This is an administration tool, not a scanner.
+- Local paths are resolved against the machine running the server, so on Windows a POSIX-looking `/tmp/x` becomes `<current drive>\tmp\x`. Every transfer reply prints the resolved path — check it.
+
+## 🧑‍💻 Development
+
+Building on this server, embedding it as a library, or changing the guards — see [README_DEV.md](README_DEV.md).
+
+## 📜 License
+
+MIT — see [LICENSE.md](LICENSE.md).