Corv v1.1发布：专为AI Agent打造的SSH执行客户端

Corv Client

面向AI代理和人类的SSH客户端。 通过名称连接。重用已认证的SSH连接。本地保存密钥。

最新版本：Corv v1.1 | 完整变更日志

AI代理使用SSH的方式与人类不同。原始SSH要求调用流程管理连接细节、身份验证配置、提示符和 终端输出。独立的调用还会重复连接建立，除非配置了OpenSSH多路复用，而长时间运行的任务通常需要 tmux、nohup或自定义脚本。

Corv专为代理驱动的基础设施构建。它允许代理通过名称连接，执行命令而不暴露密码或私钥，接收结构化的 JSON输出，重用已认证的热连接，以及分离和恢复 长时间运行的任务。人类通过交互式终端UI使用相同的已保存连接配置文件。

安装

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/khalid-src/corv-client/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/khalid-src/corv-client/main/install.ps1 | iex

使用Go

go install github.com/khalid-src/corv-client/cmd/corv@latest

更新或移除

corv update      # download and install the latest release (checksum-verified)
corv uninstall   # remove corv; add --purge to also delete saved connections

corv update 仅在你运行时才执行——Corv 永远不会在后台自行更新。

用法

交互式管理连接：

corv

终端界面支持键盘和鼠标导航来添加、编辑、 从~/.ssh/config导入以及连接。连接也可以通过命令行管理：

corv add prod-api deploy@api.example.com                    # prompts for a password if needed
corv add prod-api deploy@api.example.com --key ~/.ssh/id_ed25519
corv add prod-db dbadmin@db.example.com --jump ops@bastion.example.com
corv import                                          # import hosts from ~/.ssh/config
corv list
corv test prod-api                                   # diagnose connection stages
corv status                                          # show warm connections and active runs
corv rm prod-api

corv test <name> 打开并立即关闭一次性的SSH连接。它 检查解析、TCP可达性、堡垒路由、SSH握手、 主机密钥信任和身份验证，而不运行远程命令。添加 --json以获取结构化诊断。原始目标和地址需要 --full。corv status 报告本地代理当前保持的连接， 除非指定了--full，否则隐藏目标，并且不会启动已停止的 代理。

通过一个或多个堡垒主机后的主机使用 --jump (OpenSSH -J 语法：user@host1,user@host2) 访问。跳板主机使用 ssh-agent 或你的密钥进行身份验证；目标使用连接自身的凭证。

corv add 读取任何密码（不回显）并将其存储在本地的 加密保管库中；它永远不会作为参数传递。

corv vault reset 清除存储的SSH密码和私钥密码短语，同时 保留已保存的连接。它要求确认并在更改状态前停止本地代理。 如果加密的连接存储无法打开， Corv无法确定是其密钥不可用还是配置文件已损坏； 它会拒绝正常重置。corv vault reset --all 显式移除 本地连接存储、保管库数据、后端标记和Corv管理的本地 密钥文件。外部提供的操作系统钥匙串条目不会被移除。

交互式连接：

corv prod-api

以非交互方式运行命令（代理路径）：

corv prod-api -- uname -a
corv prod-api --json -- df -h             # structured output for tools
corv prod-api -- ./deploy.sh
echo 'cd /app && run "$X" | grep foo' | corv prod-api --json --stdin
corv prod-api --json --stdin < script.sh

一个典型的代理指令，如“检查prod-api上的磁盘使用情况”，只需要 corv prod-api -- df -h。

-- 之后的命令处理旨在按你的意图执行：

• 一个单一参数被视为远程shell命令行并原样运行， 就像ssh host "cmd" - 例如 corv srv -- "cd /app && make"；
• 多个参数作为保留的参数向量传递，每个参数都经过 shell引号处理，以便远程无法重新拆分它们 - 例如 corv srv -- sh -lc "cd /app && make"。

这为构建命令向量的调用者保留了参数边界。

For complex shell text, nested quotes, or multi-line scripts, use an stdin mode. --stdin-base64 is the cross-shell-safe option because only ASCII base64 passes through the local pipe.

Windows / PowerShell

PowerShell can mangle quoting and pipe encoding, so encode a non-trivial remote command as UTF-8 base64 and send it with --stdin-base64:

$b64=[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(@'
set -eu
cd /srv/app && ./deploy.sh
'@)); $b64 | corv prod-api --json --stdin-base64

Only ASCII base64 crosses the pipe, so the command arrives unchanged - quoting and any non-ASCII text survive intact. A simple exact argument vector can still use -- <command>.

Long commands are detached on the server automatically. If a command is still running after the broker's wait window, Corv returns the new bounded output, the run id, and exit code 75. Re-run the exact same command to watch the next delta; it attaches to the existing remote job and does not start a second copy. When the job finishes, Corv retains up to 20 MiB locally and removes the remote temporary files. If a log is larger, Corv keeps its first 4 MiB and its final section with an omission marker between them, so late failures are not lost. truncated: true in corv output --json reports this case:

corv prod-api -- ./long-install.sh
corv output <run-id> [pattern]         # bounded status/output view
# The byte-identical original command can also reattach while it is running.

CORV_WAIT controls how long the broker waits before returning a running response. It accepts bare seconds (CORV_WAIT=30) or a Go duration (CORV_WAIT=500ms, CORV_WAIT=2m) and is read from the environment of each corv invocation, so it takes effect immediately without restarting the broker. corv output <run-id> checks an unfinished detached run and finalizes it automatically once the remote exit status exists. Remote temp files are cleaned on finalization. The startup sweep removes completed remote remnants older than 24 hours; it never deletes a run without an exit status because age alone cannot distinguish an abandoned run from a silent live process. Saved local run logs and their metadata are retained for 24 hours and removed on broker startup.

corv output exits 75 while a run is active, with the remote exit code when it completes, and 1 for a Corv retrieval error. The process exit code and JSON exit_code field use the same value.

All agent-facing output is bounded. Completed responses and corv output return a middle-out view of roughly 32 KiB; running responses use a smaller budget. Pass a pattern to corv output to select relevant lines before that budget is applied. JSON responses report original_bytes, saved_bytes, returned_bytes, truncated (the retained log omitted bytes), and output_truncated (the returned view was bounded) when applicable.

Remote command execution requires a POSIX shell and standard Unix command-line tools. Windows OpenSSH servers are not supported as remote execution targets.

Use with AI agents

Corv is built for AI coding agents (Claude, Codex, and others). Ready-to-use agent instructions live in integrations/:

• Claude / Claude Code - copy integrations/claude/corv-ssh into ~/.claude/skills/ (or a project's .claude/skills/).
• Codex - copy integrations/codex/AGENTS.md into your project.

The agent then runs commands by name and reads structured output:

corv <name> --json -- <command>

For non-trivial scripts or heavily quoted commands, agents should send the remote command as UTF-8 base64:

$b64=[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(@'
set -eu
cd /srv/app && ./deploy.sh
'@)); $b64 | corv <name> --json --stdin-base64

Agents should not run corv list --full, corv doctor --full, corv test <name> --full, or corv status --full unless the user explicitly asks; those modes show local connection details. Never put passwords, private keys, API tokens, bootstrap tokens, bearer tokens, or other secrets on the command line. Corv command history records command lines.

See integrations/README.md for details.

Connection reuse

本地代理进程为每个已保存的配置文件维护一条经过身份验证的 SSH 连接。每条 corv <name> -- <cmd> 都会在已保持的连接上作为一个新通道运行，因此连接和身份验证的成本只需支付一次，而不是每条命令都支付。此行为在 Linux、macOS 和 Windows 上完全相同。

OpenSSH 也可以通过 ControlMaster 和 control socket 在 Unix 上重用连接。Corv 通过其本地代理提供了相同的热连接模型，因此代理工作流在 Windows、macOS 和 Linux 上行为一致。

代理在首次使用时自动启动，空闲15分钟后退出，并且不在服务器上安装任何内容。它仅管理SSH连接；不分配本地伪终端、不解析shell输出、也不维护远程shell状态。已保持的连接可以显式断开：

corv disconnect prod-api

范围和限制：

• 这是连接重用，而非远程会话持久化。每条命令在其自己的 shell 中运行，并带有自己的退出码；shell 状态（如工作目录）不会在命令之间传递（必要时可将它们合并到一条命令中，例如 cd /app && make）。
• 由于代理是本地的，保持的连接在本地机器休眠或网络中断时不会持久存在。跨这些事件的持久化需要远程支持，而 Corv 在设计上不依赖于此。

交互式会话打开专用连接，并将远程伪终端代理到本地终端，因此在任何平台上都不需要本地伪终端。

输出处理

Corv 为程序化使用者标准化命令输出：

• 进度条和其他回车重绘被折叠为最终状态，而不是重现为数千行；
• 包括颜色在内的 ANSI 控制序列被移除；
• 命令的 stdout 和 stderr 被一起捕获，按写入顺序交错排列，并返回到 stdout 中；使用 --json 时，stderr 字段携带 Corv 级别的错误（例如传输失败），而不是远程命令自身的 stderr；
• 已完成和正在运行的响应使用固定字节预算，并通过 ... N line(s) hidden ... 标记保留开头和结尾；corv output <run-id> [pattern] 通过相同的有限展示契约查询保留的日志；
• 失败被分类（auth_failed, unknown_host, unknown_connection, bad_request, local_error, unreachable, host_key, timeout, disconnected, resource_exhausted, ssh_error），并且远程退出码作为进程退出码传播。

安全模型

Corv 完全在客户端运行，并通过维护的 Go SSH 库（golang.org/x/crypto/ssh）实现 SSH。

• 目标服务器上无需安装任何内容。
• 连接配置文件使用与存储凭据相同的本地保管库密钥进行静态加密，因此连接文件不会以明文暴露主机、用户或路径（corv list 是查看它们的方式）。
• 密码和密钥口令存储在本地加密保管库中。保管库密钥在 Windows 上受 DPAPI 保护；在 macOS 和 Linux 上，当存在预置的 Keychain / Secret Service 密钥时，Corv 会读取它（从不自动创建），否则使用默认的 0600 密钥文件。存储的机密仅由本地代理读取并通过已验证的 SSH 连接发送；它们不会出现在命令行、日志或命令输出中。建议使用密钥认证或 ssh-agent。
• 审计日志和保存的运行日志是本地的，可能包含操作员要求 Corv 运行的命令文本或远程输出。切勿将密码、私钥、API 令牌、引导令牌、Bearer 令牌或其他机密放在命令行上；命令历史记录会记录命令行。
• 按顺序尝试认证：配置的身份文件、ssh-agent (via SSH_AUTH_SOCK on Unix, the openssh-ssh-agent named pipe on Windows), default ~/.ssh keys, then password.
• 堡垒机（ProxyJump）跳转的每个主机密钥单独验证，可以使用ssh-agent、默认密钥、每跳身份文件或从已保存配置中获取的密码/口令进行认证。
• 主机密钥通过~/.ssh/known_hosts进行验证。未知主机会被拒绝，除非交互式批准；代理程序从不自动接受未知主机。更改后的主机密钥始终被拒绝。
• 代理程序使用操作系统授权的本地IPC（Unix套接字或Windows命名管道）以及端点令牌来实现纵深防御。

架构

Corv由小型独立模块组成，使得SSH后端或输出处理器可以在不影响其他部分的情况下被替换：

包	职责
internal/profile	连接定义、存储、~/.ssh/config导入
internal/vault	本地加密的秘密存储和密钥后端
internal/sshconn	SSH传输（x/crypto/ssh）：拨号、认证、执行、Shell
internal/broker	常驻进程，每个配置文件持有一个连接
internal/output	输出处理器（折叠、剥离、边界）
internal/audit	本地命令历史
internal/tui	交互式终端UI（Bubble Tea）
internal/cli	命令行路由
internal/statelock	跨进程锁序列化本地状态写入
internal/atomicfile	崩溃安全的原子文件写入
internal/paths	磁盘上的文件位置

开发

go build ./...
go vet ./...
go test ./...

Makefile 还提供 make build 和 make build-all 命令，在具有 make 的系统上。Corv 目标为 Go 1.25+，并支持自动工具链选择；CI 和 发布版本在 Linux、macOS 和 Windows 上使用 go.mod 中固定的版本。

许可证

参见 LICENSE。