SSH Session MCP

ssh-session-mcp

中文 | English

通过 SSH 为 MCP 客户端提供持久化的共享终端运行时。

ssh-session-mcp 让用户和 AI 使用同一个 SSH PTY 会话，提供浏览器查看器，记录每条输入的操作者，并让长时间运行的远程工作易于管理，而非无状态运行。

目录

• 安装概览
• 项目结构
• 快速开始
• Docker 状态
• MCP 工具
• 配置摘要
• 安全性
• 文档
• 开发

安装概览

• 普通用户无需 git clone 此仓库。
• MCP 客户端的首选安装方式：npx -y ssh-session-mcp --viewerPort=auto
• 需要本地二进制文件的人工运维人员，首选安装方式：npm install -g ssh-session-mcp
• 官方容器发行版可发布到 docker.io/zwawa/ssh-session-mcp 等公共镜像仓库。
• git clone 仅用于贡献代码、从源代码构建和本地开发。
• 对于常见的桌面 MCP 工作流，npx 或全局 npm 安装仍是最省事的方式。Docker 主要适用于需要固定运行时、基于容器的部署或通过镜像仓库分发的场景。

存在的意义

大多数面向 SSH 的 MCP 服务可以执行命令，但无法妥善管理终端状态，难以满足真正协作的需求。

ssh-session-mcp 专注于补齐缺失的运行时层：

• 为用户和 AI 提供一个共享 PTY
• 提供浏览器终端，以便实时查看和手动干预
• 提供输入锁，防止 AI 覆盖用户的输入
• 提供安全／完整执行模式，用于处理风险命令
• 支持可配置的默认策略规则以及会话级自定义规则覆盖
• 跟踪长时间运行的远程任务
• 支持多设备和多连接配置
• 提供本地调试模式，用于演示、离线测试和提示词迭代

最适合的场景

• 在 Linux 开发板和 SSH 服务上进行 AI 辅助远程开发
• 需要真实终端的嵌入式、ROS、训练和部署主机
• 希望 AI 提供帮助，但不想放弃终端控制权的用户
• 需要清晰安装与演示流程的 MCP Marketplace 上架项目

项目结构

关键目录和文件：

路径	用途
src/	MCP 服务、SSH 会话运行时、查看器、工具和配置 CLI 的核心 TypeScript 实现
src/viewer-html/	终端查看器的 HTML 页面生成器和浏览器端脚本
test/	覆盖运行时行为、查看器契约、配置加载和仓库验证的 Vitest 测试
docs/	支持性文档，例如契约、故障分类、平台说明和 Docker 用法
docs/examples/	常规和面向 Docker 的配置示例文件
scripts/	构建、版本同步和本地运维辅助脚本
deploy/helm/	用于在单节点或分布式 v0 模式下部署到 Kubernetes 的 Helm chart
site/	GitHub Pages 落地页源文件
dist/	通过 npm run build:site 生成的静态网站输出
build/	通过 npm run build 生成的 JavaScript 输出
Dockerfile	容器镜像构建定义
docker-compose.yml	基于配置文件的 Docker Compose 示例
docker-compose.env.yml	旧版 .env 风格的 Docker Compose 示例
server.json	用于类似市场分发的 MCP 服务元数据
AGENT.md	主要的 Agent／运维操作手册
llms-install.md	面向 Agent 的安装和环境检查清单
.env.example	旧版单目标环境变量模板

快速开始

1. 优先面向 Agent 的安装（首次运行时自动下载）

如果目标是让 Claude Code、Codex 或 OpenCode 自动安装服务，请在 MCP 命令中使用 npx -y ssh-session-mcp，而不是预先全局安装。

对于 Cline Marketplace 和其他 Agent 安装程序，请参阅 llms-install.md。本仓库的结构支持通过 npx -y ssh-session-mcp --viewerPort=auto 命令一键安装。

Claude Code

claude mcp add --transport stdio ssh-session-mcp -- npx -y ssh-session-mcp --viewerPort=auto

Claude Code 文档中的 Windows 说明：原生 Windows 用户应使用 cmd /c 包装 npx，以用于 stdio MCP 服务。

claude mcp add --transport stdio ssh-session-mcp -- cmd /c npx -y ssh-session-mcp --viewerPort=auto

Codex

codex mcp add ssh-session-mcp -- npx -y ssh-session-mcp --viewerPort=auto

OpenCode

OpenCode 的 opencode mcp add 流程是交互式的。选择本地 MCP 服务并使用此命令：

npx -y ssh-session-mcp --viewerPort=auto

如果你更喜欢使用配置而非交互式流程：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ssh-session-mcp": {
      "type": "local",
      "command": ["npx", "-y", "ssh-session-mcp", "--viewerPort=auto"]
    }
  }
}

对于 stdio MCP 服务来说，这就是目前最接近“自动安装”的方式：MCP 客户端会保存命令，并在首次运行时由 npx -y 自动下载软件包。

2. 最快的本地演示

npm install -g ssh-session-mcp
ssh-session-mcp-ctl launch --local --viewerPort=auto

这会启动本地 shell，而非 SSH，并打开浏览器终端。这是在连接真实服务之前测试 MCP 运行时的最简便方式。

3. 注册为 MCP 服务

连接客户端时，请直接使用 MCP 服务二进制文件：

# Global install
npm install -g ssh-session-mcp

# Server command used by MCP clients
ssh-session-mcp --viewerPort=auto

# Claude Code
claude mcp add --transport stdio ssh-session-mcp -- ssh-session-mcp --viewerPort=auto

# Codex CLI
codex mcp add ssh-session-mcp -- ssh-session-mcp --viewerPort=auto

如果你更喜欢使用 npx 而非全局安装：

npx -y ssh-session-mcp --viewerPort=auto

4. 连接到真实 SSH 目标

根据 .env.example 创建 .env：

cp .env.example .env

SSH_HOST=YOUR_DEVICE_HOST
SSH_PORT=22
SSH_USER=YOUR_DEVICE_USER
SSH_PASSWORD=
SSH_KEY=
VIEWER_PORT=auto
AUTO_OPEN_TERMINAL=false
SSH_MCP_MODE=safe

然后启动：

ssh-session-mcp-ctl launch --viewerPort=auto

5. 多设备配置

对于多个板卡或命名目标，请创建 ssh-session-mcp.config.json：

{
  "defaultDevice": "DEVICE_A_ID",
  "devices": [
    {
      "id": "DEVICE_A_ID",
      "host": "DEVICE_A_HOST",
      "port": 22,
      "user": "DEVICE_A_USER",
      "auth": { "passwordEnv": "DEVICE_A_PASSWORD" },
      "defaults": {
        "term": "xterm-256color",
        "cols": 120,
        "rows": 40,
        "autoOpenViewer": true,
        "viewerMode": "browser"
      }
    }
  ]
}

发现顺序：

1. --config=/path/to/config.json
2. 工作区中的 ssh-session-mcp.config.json
3. 用户全局配置
4. 旧版 .env 回退方案

重要事项：

• 配置发现依据 MCP 进程的工作目录。
• 有意不支持 auth.password。请使用 auth.passwordEnv 或 auth.keyPath。
• 密钥应存放在 .env 或父级环境中，而非由仓库跟踪的 JSON 文件中。

6. Docker 状态

公开的 Docker 镜像应通过 Docker Hub 分发，GitHub Container Registry 可作为可选的次级镜像仓库：

docker.io/zwawa/ssh-session-mcp:<version>
docker.io/zwawa/ssh-session-mcp:latest
ghcr.io/zw-awa/ssh-session-mcp:<version>

连接真实 SSH 目标时，推荐使用以下容器启动命令：

docker run --rm -i \
  -p 8793:8793 \
  -e VIEWER_PORT=8793 \
  -e VIEWER_HOST=0.0.0.0 \
  -e SSH_HOST=YOUR_DEVICE_HOST \
  -e SSH_PORT=22 \
  -e SSH_USER=YOUR_DEVICE_USER \
  -e SSH_PASSWORD \
  docker.io/zwawa/ssh-session-mcp:latest

先在 shell 中导出密码，而不是直接将其写在命令行中。

使用基于配置文件的配置时，推荐使用以下启动命令：

docker run --rm -i \
  -p 8793:8793 \
  -e VIEWER_PORT=8793 \
  -e VIEWER_HOST=0.0.0.0 \
  -e SSH_MCP_CONFIG=/workspace/ssh-session-mcp.config.json \
  -v "$PWD/ssh-session-mcp.config.json:/workspace/ssh-session-mcp.config.json:ro" \
  -v "/path/to/host/keys:/workspace/keys:ro" \
  docker.io/zwawa/ssh-session-mcp:latest

等效的 Compose 示例：

docker compose up -d

参见 docker-compose.yml，其中提供了一个可直接运行的示例：它会挂载 ssh-session-mcp.config.json、在 8793 端口发布查看器，并在设置了 SSH_KEY_DIR 时使用该目录，否则回退到专用的 ./keys 目录。 完整的 Docker 指南（包括旧版 .env Compose 变体和 MCP 客户端配置片段）请参见 docs/docker.md。 面向容器的配置文件示例请参见 docs/examples/ssh-session-mcp.config.docker.example.json。

容器专属说明：

• 如果未设置，镜像会将 VIEWER_PORT 默认设为 8793，以便可靠地发布浏览器查看器。
• 镜像会在容器内将 VIEWER_HOST 默认设为 0.0.0.0，以便从主机访问映射的端口。
• 容器中的 AUTO_OPEN_TERMINAL 默认值为 false，因为通常无法从容器内有用地自动打开浏览器。
• 尽可能以只读方式挂载配置文件或 SSH 密钥。
• 最好从仓库根目录之外的目录挂载 SSH 密钥。
• 在 docker-compose.yml 中，SSH_KEY_DIR 会覆盖默认的密钥挂载路径。如果未设置，Compose 会回退到 ./keys，而不是仓库根目录。
• 避免直接在命令行中输入密码。建议使用已导出的环境变量、Compose .env 或 --env-file。
• 对于 stdio MCP 客户端，Docker 可行，但除非客户端明确偏好容器化命令，否则使用主机原生的 npx 仍然更简单。

基于 Docker 的 MCP 客户端命令示例：

# Claude Code
claude mcp add --transport stdio ssh-session-mcp -- docker run --rm -i -p 8793:8793 -e VIEWER_PORT=8793 -e VIEWER_HOST=0.0.0.0 docker.io/zwawa/ssh-session-mcp:latest

# Codex CLI
codex mcp add ssh-session-mcp -- docker run --rm -i -p 8793:8793 -e VIEWER_PORT=8793 -e VIEWER_HOST=0.0.0.0 docker.io/zwawa/ssh-session-mcp:latest

对于基于 JSON 的 MCP 客户端，同样的模式也适用：将 docker 设为命令，并将其余 run ... docker.io/zwawa/ssh-session-mcp:latest 令牌作为参数传入。

以下情况适合使用这种方式：

• 主要工作流是本地 stdio MCP 服务命令，而不是长期运行的网络服务。
• 你希望使用固定版本的 Node/运行时环境，而无需本地安装。
• 你需要通过镜像仓库为团队或受管主机分发服务。
• 你希望对 MCP 服务进程进行容器级隔离。

对于许多用户来说，发布到 npm 并推荐使用 npx -y ssh-session-mcp --viewerPort=auto，仍然是更省事的安装方式。

查看器与协作模式

浏览器查看器并非装饰，而是工作流的一部分：

• 用户可以准确看到 AI 执行了哪些操作。
• 用户接管时，AI 可以暂停。
• 密码提示、分页器和编辑器会显示为可见状态，而不再成为隐藏的故障原因。
• 会话诊断信息和历史记录让终端调试过程变得可检查。

适合市场推广的流程

对于用户：

install -> launch viewer -> connect once -> keep the session alive -> let the AI help

对于 Agent：

ssh-quick-connect -> ssh-run -> inspect output -> ssh-command-status if needed -> ssh-run again

如果希望 AI 安装工具、检查配置、连接设备并端到端地协助用户，请使用 AGENT.md。旧版 Agent 配置的兼容性说明仍保留在 AI_AGENT_GUIDE.md 中。

与无状态 MCP SSH 封装器的核心区别

• 使用共享 PTY，而非一次性命令执行
• 为用户、系统和 Agent 输入添加可识别操作者的转录标记
• 在执行危险或不合理的写入操作前检查终端状态
• 自动清理会话和查看器进程
• 按会话隔离的浏览器查看器，提供诊断信息和历史记录
• 使用 --local 进行离线测试的本地调试模式

操作模式

模式	行为
safe	每个会话的默认模式。自动拦截明显危险、需要交互或不会结束的命令。
full	每个会话单独设置。放宽防护措施以支持高级用法，但仍会拦截少数明显具有破坏性的滥用行为。

现在，每个会话都有自己的 safe / full 模式。将一个浏览器终端切换到 full 不会影响其他会话。

如有需要，可以自定义默认规则集。自定义规则现在支持：

• error：拦截命令
• warning：允许执行，但显示警告
• log：允许执行，仅添加注释

规则优先级为 error > warning > log；在同一级别内，越早的规则优先级越高。

锁定策略

浏览器终端 UI 允许操作者选择以下输入策略之一：

策略	操作者的体验
common	用户和 Agent 都可以在共享终端中输入。
user	只有用户可以输入。Agent 的写入操作会被拦截。
auto	用户可以开始输入，而不会与 Agent 冲突。用户正在主动起草输入时，Agent 的写入操作会被拦截。
agent	只有 Agent 可以输入。策略更改前，用户输入会被拦截。

当终端不可供 Agent 输入时，ssh-run、ssh-session-send 和 ssh-session-control 等工具会返回拦截响应，而不是强行向 PTY 输入内容。

MCP 工具

推荐的日常工具

工具	用途
ssh-quick-connect	连接或复用默认目标，并可选择打开查看器
ssh-run	执行命令，并检测命令是否完成及捕获退出代码
ssh-status	检查会话、查看器状态和操作模式
ssh-command-status	轮询异步命令进度
ssh-retry	通过退避策略重试不稳定的命令
ssh-session-policy-list	检查继承的默认设置和当前会话的自定义策略规则
ssh-session-policy-upsert	添加或更新会话级自定义策略规则
ssh-session-policy-remove	移除会话级自定义策略规则
ssh-session-policy-reset	将会话自定义规则重置为继承的默认设置

完整工具目录

工具	用途
ssh-session-open	使用明确指定的 SSH 参数打开会话
ssh-session-send	发送原始 PTY 输入
ssh-device-list	列出已配置的设备和默认设置
ssh-session-read	按偏移量读取缓冲的终端输出
ssh-session-watch	长轮询输出和仪表板更改
ssh-session-history	读取带行号的混合终端历史记录
ssh-session-control	发送 ctrl_c、方向键或 tab 等控制键
ssh-session-resize	调整 PTY 大小
ssh-session-list	列出已跟踪的会话
ssh-session-diagnostics	检查锁定状态、警告、运行中的命令状态和查看器运行状况
ssh-session-policy-list	显示继承的策略默认设置和当前会话规则集
ssh-session-policy-upsert	添加或更新会话专属的自定义策略规则
ssh-session-policy-remove	移除会话专属的自定义策略规则
ssh-session-policy-reset	恢复当前会话的继承规则
ssh-session-set-active	选择默认会话
ssh-viewer-ensure	打开或复用本地查看器
ssh-viewer-list	列出已跟踪的查看器进程
ssh-session-close	正常关闭会话
ssh-quick-connect	面向 Agent 的一步式连接流程
ssh-run	主要的命令执行工具
ssh-status	运行时概览
ssh-command-status	异步轮询器
ssh-retry	重试执行器

本地操作者命令

这些辅助工具供拥有查看器的工作站上的用户使用：

ssh-session-mcp-ctl status
ssh-session-mcp-ctl devices
ssh-session-mcp-ctl launch --viewerPort=auto
ssh-session-mcp-ctl launch --local --viewerPort=auto
ssh-session-mcp-ctl logs --tail=60
ssh-session-mcp-ctl cleanup

供操作者管理默认规则库：

ssh-session-mcp-config policy list --scope=merged
ssh-session-mcp-config policy set error-kubectl-delete --pattern="\\bkubectl\\s+delete\\b" --category=dangerous --action=error --priority=0 --message="kubectl delete is blocked in safe mode"
ssh-session-mcp-config policy remove error-kubectl-delete

此外，还提供等效的仓库本地命令：

npm run launch
npm run status
npm run devices
npm run logs
npm run cleanup

配置摘要

关键环境变量：

变量	含义	默认值
SSH_HOST	旧版单目标 SSH 主机	旧版模式下必填
SSH_PORT	旧版单目标 SSH 端口	22
SSH_USER	旧版单目标 SSH 用户	旧版模式下必填
SSH_PASSWORD	密码身份验证	空
SSH_KEY	本地私钥路径	空
SSH_PASSWORD_FILE	包含 SSH 密码的文件	空
SSH_KEY_FILE	包含 SSH 私钥的文件	空
SSH_MCP_INSTANCE	运行时隔离键	proc-<pid> 或由辅助程序选择
SSH_MCP_CONFIG	显式配置文件路径	自动发现
SSH_MCP_STATE_DIR	运行时状态根目录	平台默认值
VIEWER_HOST	查看器绑定主机	127.0.0.1
VIEWER_PORT	查看器端口或 auto	除非已配置，否则为 0
VIEWER_ACCESS_MODE	查看器 IP 过滤模式	由配置决定
SSH_MCP_MODE	safe 或 full	safe
SSH_MCP_LOCAL	启动本地 shell，而非 SSH	false
SSH_MCP_DEBUG	启用调试浏览器操作	false
AUTO_OPEN_TERMINAL	自动打开浏览器终端	false
SSH_MCP_LOG_MODE	off、meta 或 stderr 日志记录	off
SSH_MCP_LOG_DIR	元数据日志目录	平台默认值

分布式 v0

分布式 v0 有意实现了一个范围有限的边界：

• 支持的运行时模式：single-node 和 distributed
• 分布式模式仅共享控制平面状态：节点心跳、会话元数据、绑定元数据、命令元数据和查看器访问策略
• 当前副本不是所有者时，HTTP API 会返回 REMOTE_OWNER，HTML 页面会呈现远程所有者错误页，websocket 附加连接会以代码 4009 关闭
• 不支持跨节点 PTY 迁移
• 不支持透明的跨节点 HTTP 或 websocket 代理

分布式 v0 在实际多节点部署中需要 Redis。SSH_MCP_STORE=memory 仅用于本地骨架测试，无法在多个副本之间提供共享存储。

分布式配置：

变量	含义	默认值
SSH_MCP_RUNTIME_MODE	single-node 或 distributed	single-node
SSH_MCP_STORE	memory 或 redis	分布式模式下为 redis，否则为 memory
SSH_MCP_REDIS_URL	Redis 连接 URL	SSH_MCP_STORE=redis 时必填
SSH_MCP_NODE_ID	此副本的稳定逻辑节点 ID	运行时实例 ID
SSH_MCP_PUBLIC_BASE_URL	向其他副本公布的公共查看器基础 URL	未设置
SSH_MCP_AUTH_MODE	off 或 proxy	off
SSH_MCP_TRUST_PROXY	是否信任已验证身份的代理标头	false
SSH_MCP_AUTH_USER_HEADER	已验证用户的标头名称	x-ssh-session-mcp-user
SSH_MCP_AUTH_ROLE_HEADER	已验证角色的标头名称	x-ssh-session-mcp-role

推荐的分布式环境变量示例：

SSH_MCP_RUNTIME_MODE=distributed
SSH_MCP_STORE=redis
SSH_MCP_REDIS_URL=redis://redis:6379/0
SSH_MCP_NODE_ID=node-a
SSH_MCP_PUBLIC_BASE_URL=https://ssh-mcp.example.com
SSH_MCP_AUTH_MODE=proxy
SSH_MCP_TRUST_PROXY=true
SSH_MCP_AUTH_USER_HEADER=x-forwarded-user
SSH_MCP_AUTH_ROLE_HEADER=x-forwarded-role

在受信任的反向代理后以分布式模式运行时，代理身份验证最为实用。内置的角色映射如下：

• viewer_read：页面、会话列表/读取端点、历史记录、诊断信息、健康状态、就绪状态、指标
• viewer_write：附加输入、调整大小、控制
• session_admin：模式更改、策略更新、关闭、设为活动会话、调试 Agent 操作、本地调试会话创建

宏 / 环境变量参考

请根据安装方式使用这些变量：

变量	必需条件	可接受的值 / 示例	备注
SSH_HOST	旧版单目标 SSH 模式	YOUR_DEVICE_HOST	除非使用 ssh-session-mcp.config.json 或 --local，否则必需。
SSH_PORT	旧版单目标 SSH 模式	22	旧版模式下可选；默认值为 22。
SSH_USER	旧版单目标 SSH 模式	YOUR_DEVICE_USER	除非使用设备配置，否则必需。
SSH_PASSWORD	基于密码的身份验证	已导出的环境变量	建议通过环境变量导出密码，而不要直接将密码放在命令行中。
SSH_PASSWORD_FILE	通过密钥文件进行基于密码的身份验证	/run/secrets/ssh_password	文件内容将用作密码。这是 Docker 和 Kubernetes 密钥的推荐做法。
SSH_KEY	旧版模式下基于密钥的身份验证	/absolute/path/to/private/key	MCP 服务运行所在主机上必须存在该路径。
SSH_KEY_FILE	通过密钥文件进行基于密钥的身份验证	/run/secrets/ssh_private_key	文件内容将用作私钥。此方式适用于挂载的容器密钥。
SSH_MCP_CONFIG	基于配置文件的模式，或配置文件位于当前工作目录之外	/path/to/ssh-session-mcp.config.json	当配置文件自动发现无法满足需求时使用。
SSH_MCP_INSTANCE	多 Agent / 多客户端隔离	agent-a	如果两个 Agent 不应共享运行时状态，请使用不同的值。
SSH_MCP_STATE_DIR	覆盖运行时状态根目录	/workspace/state	控制每个实例的服务信息、查看器状态和默认日志的存储位置。在容器中将其挂载为持久化目录。
SSH_MCP_RUNTIME_MODE	分布式拓扑选择	single-node、distributed	分布式 v0 仅共享控制平面状态；不会在节点之间迁移 PTY。
SSH_MCP_STORE	分布式状态后端	memory、redis	任何实际的多节点部署都应使用 redis。memory 仅用于本地分布式骨架测试。
SSH_MCP_REDIS_URL	启用 Redis 后端	redis://redis:6379/0	当 SSH_MCP_RUNTIME_MODE=distributed 且 SSH_MCP_STORE=redis 时必需。
SSH_MCP_NODE_ID	稳定的分布式节点 ID	node-a	多个副本共享 Redis 且需要持久化所有者 ID 时很有用。
SSH_MCP_PUBLIC_BASE_URL	此节点的公共路由提示	https://ssh-mcp.example.com	用于 REMOTE_OWNER 负载和集群状态输出。
SSH_MCP_AUTH_MODE	查看器身份验证模式	off、proxy	仅建议在可信反向代理之后使用 proxy。
SSH_MCP_TRUST_PROXY	信任查看器身份标头	true、false	必须与 SSH_MCP_AUTH_MODE=proxy 一同启用。
SSH_MCP_AUTH_USER_HEADER	代理身份验证的查看器用户标头	x-forwarded-user	标头名称会在内部规范化为小写。
SSH_MCP_AUTH_ROLE_HEADER	代理身份验证的查看器角色标头	x-forwarded-role	角色以逗号分隔，并映射到 viewer_read、viewer_write、session_admin。
VIEWER_HOST	自定义查看器绑定地址	127.0.0.1、0.0.0.0	在容器中使用 0.0.0.0；除非需要远程访问，否则在常规主机安装中使用 127.0.0.1。
VIEWER_PORT	启用查看器	auto、0、8793	auto 会选择空闲端口，0 会禁用查看器；Docker 中最好使用固定端口。
VIEWER_ACCESS_MODE	查看器访问控制模式	allow_all、allowlist、denylist	通常在查看器主页中编辑。仅在只通过 localhost 访问时保留 allow_all。
AUTO_OPEN_TERMINAL	自动打开查看器标签页	true、false	在容器中通常设为 false。
SSH_MCP_MODE	运行时安全模式	safe、full	建议默认使用 safe。
SSH_MCP_LOCAL	本地演示模式	true、false	启动本地 shell，而不是 SSH。
SSH_MCP_DEBUG	浏览器调试控制	true、false	用于演示和故障排查。
SSH_MCP_LOG_MODE	运行时元数据日志记录	off、meta、stderr	meta 会写入 JSONL 元数据日志，但不会存储原始机密信息。stderr 是推荐的容器模式，因为它在暴露结构化日志供容器运行时读取的同时，会保留 MCP 的 stdio 传输方式。
SSH_MCP_LOG_DIR	覆盖元数据日志目录	/workspace/state/instances/<instance>/logs	主要用于 SSH_MCP_LOG_MODE=meta；在 stderr 模式下会忽略。
SSH_KEY_DIR	Docker Compose 基于配置文件的示例	/path/to/host/keys	在 docker-compose.yml 中可选；未设置时会回退到 ./keys。
SSH_SESSION_MCP_IMAGE	Docker Compose 镜像覆盖值	docker.io/zwawa/ssh-session-mcp:latest	如果你镜像该镜像或测试其他标签，请覆盖此值。

最低必需设置

选择以下一种最低配置组合：

• 本地演示：SSH_MCP_LOCAL=true 和 VIEWER_PORT=auto
• 使用密码的传统 SSH：SSH_HOST、SSH_USER、SSH_PASSWORD
• 使用密钥的传统 SSH：SSH_HOST、SSH_USER、SSH_KEY
• 基于配置文件的模式：ssh-session-mcp.config.json，以及该配置文件引用的任何 passwordEnv 变量
• Docker Compose 配置文件模式：ssh-session-mcp.config.json，可选的 SSH_KEY_DIR、可选的 SSH_SESSION_MCP_IMAGE

容器运行时说明

• 容器现在默认设置 SSH_MCP_LOG_MODE=stderr，使日志输出到容器运行时，同时避免破坏 stdio MCP 传输。
• 如果希望查看器策略、服务信息和状态文件在容器重启后仍然保留，请持久化挂载 SSH_MCP_STATE_DIR。
• 分布式多节点部署需要 Redis，并且每个副本都需要可路由的 SSH_MCP_PUBLIC_BASE_URL。
• 分布式 v0 不提供跨节点 PTY 迁移或透明的跨节点代理。收到 REMOTE_OWNER 时，请将请求路由到所有者节点。
• 健康检查端点：
  • /livez：进程存活检查
  • /readyz：就绪检查
  • /metrics：Prometheus 文本指标
• 单实例 Kubernetes 基线示例：docs/examples/ssh-session-mcp.k8s.single-instance.yaml
• 分布式 Kubernetes 基线示例：docs/examples/ssh-session-mcp.k8s.distributed.example.yaml
• Kubernetes 首选安装路径：deploy/helm/ssh-session-mcp

配置文件示例：docs/examples/ssh-session-mcp.config.example.json

安全

• 本软件包绝不会要求将原始密码写入受版本控制的 JSON 配置文件。
• .env 会被 git 和 npm 忽略。
• 查看器 HTTP 默认绑定到 localhost。
• MCP 服务将终端模式和输入锁定视为一等安全信号。
• CI 会使用 Trivy 扫描文件系统和容器镜像中的高危与严重漏洞。
• CI 会安装经过校验和验证的固定版本 Trivy CLI，而不是依赖版本浮动的第三方操作标签。
• 发布构建会为已发布的 GHCR 镜像摘要生成 CycloneDX SBOM，并将其附加到 GitHub 发布版本。
• 发布构建会使用无密钥 Cosign 对已发布的 GHCR 镜像摘要签名。
• GHCR 摘要是主要验证方式。Docker Hub 用于分发，而非主要的签名验证目标。

完整政策请参阅 SECURITY.md。

平台说明

• Windows 10/11：一流的主机环境
• Linux：非常适合无头 MCP + 浏览器查看器工作流
• macOS：支持标准 Node.js 路径
• 远程 Linux 主机：一流目标平台

更多详情：docs/platform-compatibility.md

文档

• AGENT.md
• AI_AGENT_GUIDE.md
• llms-install.md
• docs/contracts.md
• docs/failure-taxonomy.md
• docs/acceptance-scenarios.md
• docs/docker.md
• docs/kubernetes.md
• docs/ingress-proxy-auth.md
• CHANGELOG.md

开发

只有在想要修改源代码、在本地运行测试或构建发布产物时，才需要克隆此仓库。

npm install
npm run build
npm run test
npm run validate:repo
npm run build:site

此仓库包含的 GitHub Actions 可以：

• 在推送和拉取请求时运行 CI
• 从 dist/ 部署 GitHub Pages 落地页
• 构建带标签的 GitHub Release，并附上 npm 软件包压缩包

许可证

Apache-2.0。请参阅 LICENSE。