OctSSH - 更优雅的让AI操控你的服务器

VibeCoding 的时候，我突然想到，能不能让 agent 帮我上服务器部署代码呢，于是，我开发了

OctSSH 是一个 MCP 服务，允许 LLM 安全、可控地访问您的服务器 shell 环境。

注意

默认模式（stdio）下，OctSSH 只支持连接到您本机 ssh_config 中配置好的免密登录的机器。

那么... OctSSH 有什么特别之处呢？

工具一览

OctSSH 提供了一套完整的同步 / 异步工具，防止 LLM 等待长任务超时。

🖥️ 命令执行

工具	说明
`exec(machine, command, confirm_code?)`	同步执行短命令
`sudo-exec(machine, command, confirm_code?)`	以 root 身份同步执行（`sudo -n`）

⏳ 异步任务

工具	说明
`exec-async(machine, command, confirm_code?)`	后台运行长任务（基于 `screen`）
`exec-async-sudo(machine, command, confirm_code?)`	以 root 身份后台运行
`write-stdin(session_id, data, append_newline?)`	向运行中的异步任务写入 stdin
`get-result(session_id, lines?)`	查看异步任务输出
`grep-result(session_id, pattern, ...)`	按正则搜索任务日志
`cancel(session_id)`	终止任务

🛠️ 辅助

工具	说明
`sleep(time)`	暂停等待（轮询场景适用）

注意：在 HTTP Serve 模式下，上述工具直接作用于本机，不需要 machine 参数，且不暴露 SSH 传输工具（upload / download）。

安全设计

OctSSH 设计了一套 Virtual Mode 操作模式和 Confirm Code 安全验证，工作流程如下：

🔒 安全机制：Virtual Mode

我们不希望 AI 变成毁灭世界的终结者，所以设计了 Virtual Mode。

当 AI 尝试以下操作时，OctSSH 不会直接执行，而是返回 confirm_code 确认码：

📁 文件覆盖：上传的目标路径已存在同名文件
💀 高危指令：rm -rf 等"删库跑路"级命令
🔍 正则拦截：配置中自定义的敏感模式

执行流程示例：

AI 调用 exec("web", "rm -rf /var/www/html")
🛑 OctSSH 拦截：该操作将递归删除目录 -> 返回 confirm_code: a1b2c3 + 受影响文件预览
👤 用户检查后告诉 AI："确认执行"
✅ AI 调用 exec("web", "rm -rf /var/www/html", "a1b2c3") -> 真正执行

快速开始

安装

npm install -g @aliyahzombie/octssh
octssh init

启动模式

1. 默认 Client 模式 (stdio)

在本地运行，通过 SSH 控制远程机器（读取 ~/.ssh/config）：

octssh

2. Streamable HTTP Server 模式 (本机控制)

安装在目标机器上，通过 HTTP 接口控制该机器本身（无需 SSH 中转，适合反向代理或远程直连）。

在此模式下，OctSSH 仅控制本机。

octssh serve

默认监听：127.0.0.1:8787 (可通过 OCTSSH_SERVE_HOST / OCTSSH_SERVE_PORT 覆盖)
认证：启动时会打印随机生成的 Key；客户端需带 Header X-OctSSH-Key: <key>
- 固定 Key 配置：export OCTSSH_SERVE_KEY="my-secret"

工具前缀（可选）

如果你需要同时运行多个 OctSSH 实例（避免工具名冲突），可以给所有暴露的工具增加前缀：

export OCTSSH_TOOL_PREFIX="us1_"

示例：list 会变成 us1_list。

write-stdin（异步任务交互输入）

write-stdin 用于向正在运行的 exec-async 会话写入 stdin（给长任务/交互式脚本喂输入）。

典型流程：

用 exec-async 启动一个会读取 stdin 的长任务
用 write-stdin(session_id, data) 发送输入
用 get-result(session_id) 轮询输出

注意：

append_newline 默认是 true。
单次写入最大 64KiB。
这里的 stdin 是持续的流：不会发送 EOF。如果你的程序需要 EOF 才会退出，请用 cancel 结束会话。
如果设置了 OCTSSH_TOOL_PREFIX，工具名也会带前缀（例如 us1_write-stdin）。

接入 MCP 客户端

通用配置 (stdio)

向你的 MCP 客户端配置文件添加：

{"mcpServers": {
    "octssh": {
      "command": "octssh",
      "args": []
    }}}

Claude Code CLI

claude mcp add octssh -- octssh

OpenCode CLI

{"mcp": {
    "octssh": {
      "type": "local",
      "command": "octssh",
      "args": [],
      "enabled": true
    }}}

或者：

opencode mcp add octssh --command octssh

本项目会连接到您的真实服务器（或在本机执行命令），请您务必仔细审查 LLM 的操作。使用该项目则代表您同意开发者不对任何可能的误操作负责。