remote-dev

为什么需要 remote-dev？

在用 Claude Code、Codex、Kimi Code 或 Cursor 做远端开发（比如连到算力服务器调大模型、改算子、查日志）时，如果只靠手写一条条 ssh host "sed ..." 或 scp 命令，不仅容易被转义符搞崩，还会丢失本地工具的行号读取、精确替换、补丁校验和后台任务交互体验。

remote-dev 把 Agent 熟悉的本地工具（Read、Write、Edit、Bash、Glob、Grep、apply_patch 等）完整做了一套远端同款（remote.*）。只要加上目标机器的 host / port（或者给服务器起个别名 alias），Agent 就能直接操作远端主机甚至直接钻进远端正在跑的 Docker 容器里干活：

• 19 个核心远端工具（外加 60+ 个 6-Harness 原生别名），跟本地习惯一模一样：支持通过 MCP Server（remote-dev server）挂载给 AI 助手，也支持在终端用 remote-dev <子命令> 直接调用。

• 免折腾直通远端 Docker 容器：不用在容器里装 sshd 或任何后台服务，只要在参数里加上 container="你的容器名"，文件读写、打补丁、跑测试就全在容器里执行。

• SSH 长连接复用 + 独立控制通道：内置跨平台（macOS / Linux / 原生 Windows）SSH 连接池。哪怕后台正在跑几个小时的大编译或压测，你随时查状态（job_status）、看实时日志（job_tail）或紧急喊停（job_stop）都秒回、绝不卡死。

• 安全稳妥，不瞎猜、不乱试：每次操作必须明确指定连哪台机器，不会因为你在哪个本地目录就偷偷连错服务器；内置高危破坏性命令拦截保护（v0.11.2+ 自动拦截 npu-smi set -t reset 芯片复位、reboot / shutdown 整机重启关机、磁盘格式化等危险指令）；改文件前如果发现文件被别人动过会自动拦截提醒；如果网络半路断开、不确定命令到底跑没跑上，会如实报告“状态不确定”，绝不自作主张再跑一遍闯祸。

flowchart LR
    Agent["🤖 AI 编程助手 / 开发者<br/>(Claude Code / Codex / Kimi / Cursor)"]
    MCP["⚡ remote-dev<br/>(本地 MCP Server & CLI)"]
    Pool["🔗 SSH 二进制 RPC 连接池<br/>(8 常规通道 + 2 独立控制通道)"]
    Host["🖥️ 远端 Linux 宿主机<br/>(文件读写 / 搜索 / 进程管理)"]
    Container["🐳 远端运行中的 Docker 容器<br/>(docker exec 直通，免装 sshd)"]

    Agent -->|"调用 remote_read / remote_bash 等"| MCP
    MCP -->|"连接复用 & 并发限流"| Pool
    Pool -->|"SSH 直连"| Host
    Host -->|"附加 container 参数"| Container

Related MCP server: ssh-mcp

快速开始

直接复制下面这句话发给你的 Claude Code、Codex、Kimi Code、DeepSeek Harness（DSH）或 Google Antigravity（AGY），由 AI Agent 自动完成安装和 MCP 配置：

帮我安装并配置 https://github.com/mindie-agent/remote-dev

如果你是收到上述指令的 AI Agent，请按以下步骤完成 remote-dev 的环境检查与自动接入：

1. 检查基础依赖：确认本机有 Python >= 3.11、uv（或 pip）以及 ssh 客户端（Windows 需 Git for Windows 内置的 usr/bin/ssh.exe）。

2. 按当前宿主客户端写入 MCP 配置（无需提前克隆仓库，uvx 会直接拉取运行）：

   • Claude Code（写入项目根目录 .mcp.json 或运行 claude mcp add）：

     claude mcp add remote-dev -- uvx --from git+https://github.com/mindie-agent/remote-dev@main remote-dev server

   • Cursor（写入 .cursor/mcp.json）或通用 .mcp.json：

     {
       "mcpServers": {
         "remote-dev": {
           "type": "stdio",
           "command": "uvx",
           "args": [
             "--from",
             "git+https://github.com/mindie-agent/remote-dev@main",
             "remote-dev",
             "server"
           ],
           "env": {
             "REMOTE_DEV_DEFAULT_USER": "root",
             "REMOTE_DEV_DEFAULT_ROOT": "/",
             "REMOTE_DEV_DEFAULT_CWD": "/"
           }
         }
       }
     }

   • Kimi Code（写入 .kimi-code/mcp.json，注意不要带 type 字段）：

     {
       "mcpServers": {
         "remote-dev": {
           "command": "uvx",
           "args": [
             "--from",
             "git+https://github.com/mindie-agent/remote-dev@main",
             "remote-dev",
             "server"
           ],
           "startupTimeoutMs": 30000,
           "toolTimeoutMs": 120000
         }
       }
     }

   • OpenAI Codex（追加到 .codex/config.toml）：

     [mcp_servers.remote_dev]
     command = "uvx"
     args = ["--from", "git+https://github.com/mindie-agent/remote-dev@main", "remote-dev", "server"]

3. 验证安装可用：在终端运行以下命令确认 CLI 与 MCP 服务正常就绪：

   uvx --from git+https://github.com/mindie-agent/remote-dev@main remote-dev --help

4. 告知用户：提示用户开启新会话即可直接说“帮我连上 <服务器IP> 看看 /work 目录下的代码”。

一次录入密码，所有入口共用

remote-dev 提供统一的 SSH 认证、公钥维护与凭据管理底座。只需录入一次密码，mindie-coordinator 的机器注册、npu-top 的连通性检查以及各宿主插件的远端工具即可直接共用同一套连接配置：

# 隐藏输入一次密码；验证通过后自动安装并验证免密公钥
remote-dev auth setup --host 192.0.2.10 --port 22 --user root --prompt

# 若目标服务器仅允许密码登录，可保存密码供后续进程直接复用
remote-dev auth setup --host 192.0.2.10 --port 22 --user root --prompt --no-install-key

# 查看认证状态或直接执行远端命令
remote-dev auth status --host 192.0.2.10 --port 22 --user root
remote-dev bash --host 192.0.2.10 --port 22 --user root --command 'hostname'

• 跨会话与跨组件持久化（~/.mindie/ssh）：认证档案按精确的 host + port + user 存储在当前系统用户的 ~/.mindie/ssh 目录（Windows 原生环境为 %USERPROFILE%\.mindie\ssh），与单个聊天窗口或工作目录解耦，切换终端、会话或插件后无需重新录入。可通过 REMOTE_DEV_AUTH_DIR 或 REMOTE_DEV_CREDENTIAL_FILE 自定义路径。

• 公钥优先与自动修复：首次配置优先验证现有 OpenSSH 密钥，需要时自动在 ~/.mindie/ssh/keys/id_ed25519 生成无口令私钥并完成公钥安装。若后续远端公钥失效，开发调用会在下发业务命令前自动用已保存的密码修复公钥或回退为密码模式（只读探测与监控直接回退密码认证，不改写远端 authorized_keys）。

• 无弹窗本地文件保护：凭据保存在本地 credentials.json（POSIX 目录权限 0700、文件权限 0600），不调用系统钥匙串、不触发桌面授权弹窗。支持通过 --prompt、--password-stdin 或一次性环境变量（--password-env VARIABLE / MCP password_env）安全导入，请勿将明文密码直接写入命令行参数或聊天文本。密码更新后重新运行 auth setup --prompt 即可，执行 remote-dev auth forget 可随时清除本地保存的配置与密码。

真实使用场景

场景 1：检查远端服务器连通性，看看到底卡在哪一步

连不上远端或者觉得 SSH 慢？用 probe --diagnose-connection 一键测出本地准备、TCP 握手/认证、远端探测和流回收每一段的耗时：

remote-dev probe --host 192.0.2.10 --port 22 --diagnose-connection

场景 2：不用进容器装 SSH，直接在远端 Docker 容器里改代码、跑测试

算力机上已经起了个叫 vllm-dev 的容器？加上 --container vllm-dev，所有读写和命令自动通过宿主机的 docker exec 在容器内部完成：

# 检索容器里的源码
remote-dev grep --host 192.0.2.10 --port 22 --container vllm-dev --path /workspace/vllm --pattern "PagedAttention"

# 在容器里直接跑 pytest
remote-dev bash --host 192.0.2.10 --port 22 --container vllm-dev --cwd /workspace/vllm --command "pytest tests/kernels -q"

场景 3：运行耗时任务，随时看增量日志或安全停止

跑一个耗时很长的训练或评测脚本时，如果超过等待时间（yield_time_ms，默认 10 秒）还没跑完，remote-dev 会自动返回一个 session_id（即 job_id），让你随时跟进或停止：

# 查看后台作业最新状态
remote-dev job-status --host 192.0.2.10 --port 22 --job-id <job_id>

# 增量拉取最新日志输出（按字节游标续读，不会截断中文字符）
remote-dev job-tail --host 192.0.2.10 --port 22 --job-id <job_id>

# 需要取消时，把整个进程树（包含衍生子进程）干净停掉
remote-dev job-stop --host 192.0.2.10 --port 22 --job-id <job_id>

场景 4：给常用服务器配置简短别名（alias）

在项目目录下放一个 endpoints.local.json（或设置环境变量 REMOTE_DEV_ENDPOINTS_FILE），以后调用只需传 --alias dev-box：

{
  "endpoints": {
    "dev-box": {
      "host": "192.0.2.10",
      "port": 22,
      "user": "root",
      "container": "vllm-dev",
      "root": "/workspace",
      "cwd": "/workspace/vllm"
    }
  }
}

本地工具与远端工具对照表

如何指定目标服务器与常用配置

为了防止连错机器，remote-dev 永远不会从你的本地文件夹名字去猜远端服务器。每次调用可以通过以下 3 种方式之一指定目标：

1. 直接传连接信息：指定 host + port（可选附带 container、user、root、cwd、runtime_env_file、identity_file）。

2. 传机器别名（alias）：从 REMOTE_DEV_ENDPOINTS_FILE 或当前目录下的 endpoints.json / endpoints.local.json 查找对应机器配置。

3. 传自定义选择器（Resolver 插件）：上层工具可以通过 REMOTE_DEV_RESOLVERS 注册自己的查机器插件（例如 --selector lab=gpu-1）。

常用环境变量一览：

文档导航

想了解更深入的架构设计、各家 AI 客户端的参数兼容细节或底层连接池原理？请查阅文档中心：

仓库目录结构

remote-dev/
├── remote_dev/              # 核心 Python 包（SSH 连接池、容器直通、进程管理、MCP Server 与 CLI）
├── examples/                # Claude Code / Codex / Kimi / Cursor 等客户端配置模板与插件示例
├── docs/                    # 中英双语详细技术文档
├── tests/                   # 单元测试套件（使用本地 Mock 传输，无需连真实服务器即可跑通）
├── DESIGN.md                # 英文架构设计说明
└── CLIENT_COMPATIBILITY.md  # 英文客户端兼容性与参数对照说明

许可证

本项目采用 MIT License 开源。