From 8d4ed1135dac762a0910b0cc79c17a359be6c95d Mon Sep 17 00:00:00 2001 From: Jeongkyu Shin Date: Fri, 17 Jul 2026 15:54:45 +0900 Subject: [PATCH] docs: state native Windows client support is not supported The bssh crate does not build for a Windows target today: the top-level Cargo.toml declares nix, signal-hook, and libc unconditionally, and the PTY/agent/keygen code paths are un-gated for Unix, with no Windows CI or release target. Add an explicit "Platform Support" section to README.md that states native Windows client execution is not currently supported, recommends WSL2 as the path today, and links to #213 for the full blocker list. Update the existing "Cross-Platform" feature bullet to point at the new section, and extend the related note in docs/architecture/ssh-client.md so the SSH-agent-on-Windows caveat also cross-references the broader platform-support status and the issue. No code changes: the known blockers are already tracked in #213 itself, and native Windows support remains an optional, separately-scoped follow-up. Refs #213 --- README.md | 7 ++++++- docs/architecture/ssh-client.md | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d1061eb7..3c1327c5 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,18 @@ A high-performance SSH client with **SSH-compatible syntax** for both single-hos - **Progress Tracking**: Real-time progress indicators with smart detection (percentages, fractions, apt/dpkg) - **Flexible Authentication**: Support for SSH keys, SSH agent, password authentication, and encrypted key passphrases - **Host Key Verification**: Secure host key checking with known_hosts support -- **Cross-Platform**: Works on Linux and macOS +- **Cross-Platform**: Works on Linux and macOS (see [Platform Support](#platform-support) for Windows status) - **Output Management**: Multiple output modes (TUI, stream, file, normal) with auto-detection - **Interactive Mode**: Interactive shell sessions with single-node or multiplexed multi-node support - **SSH Config Caching**: High-performance caching of SSH configurations with TTL and file modification detection - **Configurable Timeouts**: Set both connection timeout (`--connect-timeout`) and command execution timeout (`--timeout`) with support for unlimited execution - **SSH Keepalive**: Configurable keepalive settings (`--server-alive-interval`, `--server-alive-count-max`) to prevent idle connection timeouts +## Platform Support + +- **Linux and macOS**: Fully supported, including SSH agent authentication (`-A`), PTY-based interactive sessions, and every CLI feature documented here. +- **Windows (native)**: Not currently supported as a client. The `bssh` crate does not build for a Windows target today because of unconditional Unix-only dependencies (`nix`, `signal-hook`, `libc`) and un-gated PTY/agent code; there is no Windows CI job or release artifact. Use **WSL2** to run `bssh` on Windows in the meantime. See [#213](https://github.com/lablup/bssh/issues/213) for the current status and the known blockers to native Windows client support. + ## Installation ### Install via Homebrew (macOS/Linux) diff --git a/docs/architecture/ssh-client.md b/docs/architecture/ssh-client.md index 29df9d26..dea0fbe1 100644 --- a/docs/architecture/ssh-client.md +++ b/docs/architecture/ssh-client.md @@ -615,7 +615,7 @@ let auth_method = auth_ctx.determine_method?; - Uses `zeroize` crate to clear passwords and passphrases from memory - Secure passphrase prompts via `rpassword` crate - No credential caching or storage -- Platform-specific handling (SSH agent not supported on Windows) +- Platform-specific handling (SSH agent not supported on Windows; native Windows client execution is not currently supported at all, see the README's [Platform Support](../../README.md#platform-support) section and [#213](https://github.com/lablup/bssh/issues/213)) **Code Reduction:** - Eliminated ~130 lines of duplicated authentication logic