Conning

Conning

轻量的本地 SSH 控制器，供人类和 Agent 使用。 Conning 是运行在你自己机器上的一个小型 CLI 和 MCP 服务。它通过普通的 OpenSSH，在你的测试机器上运行命令、长时间任务并复制文件。你通过终端控制它；你的 Agent（Claude Code、Codex、Cursor……）则通过 MCP 工具使用相同的四个命令，并获得一致的输出。密钥由 Conning 保管，因此 Agent 永远看不到密码；任何有风险的操作都需要你批准。

conn targets add lab --host 10.0.0.5 --user tester   # asks for the rest, pins the host key
conn run lab uname -a                                 # exit code first, then the output
conn run -t lab apt upgrade                           # you, at a terminal: live, like ssh -t
conn ssh lab                                          # you: a shell there, same login and jump hosts
conn targets mode lab auto                            # optional: let the agent run anything there

状态：早期版本（0.6）。 Linux、macOS 和 Windows 目标均可使用，并支持长时间任务、传输、跳转主机和审批。有关目前的所有决策，请参阅 docs/design.md。

它是什么

• 轻量。 一个 Python 包，无需守护进程：Agent 启动 MCP 服务时，它会通过 stdio 运行。每轮使用四个工具约消耗 1k 个 token。结果开头会显示退出代码，默认上限为 8 KB，并提供分页句柄以查看其余内容；向多个目标扇出时，相同结果会合并。
• 本地运行。 它与你和你的 Agent 一起运行。目标只需要支持入站 SSH，不需要在目标上安装任何内容。密钥保留在原处（OS 密钥链、op://、ssh-agent）：目标文件只保存引用，工具不会返回任何密钥。
• SSH。 底层使用普通 OpenSSH，绝不使用你的 ~/.ssh/config：每个目标都会生成独立配置、固定主机密钥、关闭转发，并支持跳转主机。Windows 目标需要 OpenSSH 和 PowerShell 7。
• 供人类和 Agent 使用。 每个目标都有一种模式：ask 或 auto。在 ask 模式下，只允许运行只读命令和你设置的允许规则；其他操作都会等待你的批准；“始终允许”只记住两个词，因此 systemctl status 不会放行 systemctl stop。只有你能授予信任：在 Agent 客户端的提示中、通过 conn watch 或在终端中操作。

安装

uv tool install conning        # or: pipx install conning
conn mcp install claude        # or codex, cursor, opencode, pi: adds the server, its skill, and denies raw ssh/scp

若要启用读取目标信息（其文件、命令和 shell 历史记录）的 Tab 补全，请运行一次 conn completion install；它会在你的 bash、zsh 或 fish rc 文件中添加一行。如果缺少该设置，conn doctor 会提醒你。在目标上设置 history = false，即可避免读取其 shell 历史记录（D53）。

MCP 服务无需安装：

claude mcp add conning -- uvx conning mcp

或在 Docker 中运行服务

docker run -i --rm --network host \
  -v ~/.config/conning:/conning \
  -v "$SSH_AUTH_SOCK":/ssh-agent -e SSH_AUTH_SOCK=/ssh-agent \
  ghcr.io/eranyonai/conning:latest

此镜像仅包含 Python、OpenSSH 客户端和 Conning。目标、固定的主机密钥和任务输出都存放在 /conning 卷中，且 conn 以该文件夹的所有者身份运行，因此它在该文件夹中写入的文件在主机上仍归你所有。在 Mac 上使用 Docker Desktop 时，请改用 -v /run/host-services/ssh-auth.sock:/ssh-agent 转发 Agent。以下两项仍由你的机器负责（D46）：

• 审批。 conn targets add、conn approve、conn allow 和启用 auto 都需要你的终端。在主机上安装 CLI，并让它指向同一文件夹：CONNING_HOME=~/.config/conning conn approve a:1。在 Agent 客户端中审批则和往常一样，可以在容器内操作。
• 密钥。 容器无法访问 OS 密钥链，因此请使用 env: 或 op:// 引用，或者按上述方法转发 ssh-agent 并使用密钥。运行 docker run --rm ... conning doctor 可检查其余设置。

实验室 LAN 或 VPN 上的目标需要使用 --network host（Linux），或配置容器可用的路由。

Agent 的四个工具

工具	功能
targets(filter?, check?)	每个目标占一行：名称、操作系统、shell、主机、用户、标签、模式。绝不会包含机密。
run(target, cmd | argv, wait=30, max_bytes=8192, ...)	在一个目标、目标列表或 tag:<tag> 上运行命令。首先返回退出代码。如果 wait 秒后仍在运行，则返回作业 ID（wait=0 表示异步运行）。
read(id, wait?, range?, grep?, signal?)	长轮询作业以获取新行、分页读取已保存的输出，或读取远程文件。
transfer(source, dest)	在 local:<path> 和 <target>:<path> 之间复制文件，并通过 sha256 校验。

没有 MCP 的 Agent 可以通过 conn CLI 使用相同的命令；输出完全相同。

面向 Agent：CLI 参考

此代码块由 conn help --markdown 生成，因此你无需调用 --help。测试会确保它 与代码保持同步。

# Agent commands (same output as the MCP tools)

conn targets [--check] [filter]
    List targets: name, OS, shell, host, user, tags, mode. Never secrets.

conn run [--wait WAIT] [--timeout TIMEOUT] [--cwd CWD] [--shell] [-t]
                [--max-bytes MAX_BYTES] [--grep GREP]
                target [argv ...]
    Run a command on one target, a list, or tag:<tag>. Exit code first.

conn read [--wait WAIT] [--range RANGE] [--grep GREP] [--signal {INT,TERM,KILL}]
                 [--max-bytes MAX_BYTES]
                 id
    Page a job (new lines only), a saved output, an approval, or a remote file.

conn transfer source dest
    Copy files: local:<path> to <target>:<path>, or back. sha256 checked.

# At a terminal

conn ssh target
    Human only: an interactive shell on a target, with its login, key, port and jump hosts.

# Targets (conn targets <verb>)

conn targets add [--host HOST] [--user USER] [--like TARGET] [--port PORT]
                        [--jump TARGET] [--auth {ssh-agent,key,password}] [--secret SECRET]
                        [--key KEY] [--os {linux,windows,darwin}] [--mode {ask,auto}] [--tag TAG]
                        name
    Add a target. Without a terminal it is saved as pending until a human approves it.

conn targets import [--match MATCH]
    Import hosts from ~/.ssh/config as pending targets (unsafe options dropped).

conn targets test name
    Probe a target: reachability, OS, shell, pinned host key.

conn targets mode target [{ask,auto}]
    Show or set ask or auto; auto runs anything without asking and needs a human.

conn targets rename old new
    Human only: rename a target; its host keys, password and pending work follow.

conn targets rm name
    Remove a target and its pinned host key.

# Trust

conn approve [--always] what
    Human only: make a target live, or allow a pending command a:<id>.

conn allow target [words ...]
    Human only: let a command run without asking (no words: list the rules).

conn deny target words [words ...]
    Remove an allow rule, so the command asks again (no terminal needed).

# This machine

conn watch [--history HISTORY] [--no-prompt]
    Live control room: every command on every target, job output, approval prompts.

conn doctor
    Check this machine's setup: config and state dirs, ssh, keychain, targets.

conn mcp [--approve-in-client | --no-approve-in-client] <serve|install> ...
    Run the MCP server on stdio, or install it into an agent client.

conn completion {bash,zsh,fish,install}
    Tab completion that reads the target; conn completion install turns it on in your shell.

conn help [--markdown]
    Show this help; --markdown prints the block cached in README.md.

一个目标对应一台机器上的一个登录账号。若要以另一个用户身份使用同一台机器，请再次添加： conn targets add lab-tester --like lab --user tester 会复制主机、端口、操作系统和标签，并询问新 用户的密码。conn targets 会显示每个目标使用的用户。

位于堡垒机之后的目标会将堡垒机指定为跳转主机：先将堡垒机添加为目标，然后运行 conn targets add lab --host 10.0.0.5 --user tester --jump gw。每一跳都有自己的登录账号和固定的 主机密钥，而 conn targets import 会保留指向它所导入的另一个主机的 ProxyJump。Agent 也能看到 堡垒机这个目标；在 ask 模式下，未经你允许，它只能在那里运行只读命令。

在 Agent 会话中通过 conn targets add 添加的目标会保存为待处理状态。在人工运行 conn approve <name> 之前，它不会执行任何操作；该命令会显示主机、固定的主机密钥指纹，以及 机密的来源。

不在目标允许列表中的命令会返回 status=pending_approval id=a:<id>，并向人工发送桌面 通知。人工可以在以下三个地方之一作出回应（允许一次、始终允许其前两个词，或拒绝），然后 Agent 通过 read a:<id> 获取结果：

• 在 Agent 客户端中：任何支持 elicitation 的 MCP 客户端都会在命令排队前显示问题， 获批的命令会在同一次调用中运行。不支持此功能的客户端会退回到以下两种方式。如果客户端会自行回答 此类提示，而不是询问你，请使用 conn mcp --no-approve-in-client 运行服务。
• 在 conn watch 中，它还会实时显示每条命令及其输出。
• 在任意终端中运行 conn approve a:<id>。如果你在终端中自行运行 conn run，它会直接在终端中询问你 并打印结果。

uname、hostname、df、ps、ls、ip addr、systemctl status 和 journalctl 等只读命令可在每个目标上直接运行，无需逐次询问；系统会对每条命令进行检查，因此其可变形式（如 hostname x、 ip addr add）仍需询问，而目标条目中的 safe = false 会关闭此列表。 conn allow <target> make test 可让另一个命令从此无需询问即可运行；conn deny 会撤销该设置。每条命令、每次回答和每次规则变更都会写入哈希链式审计日志；如果出现问题， conn doctor 会检查你的设置。

安全模型

模式	Agent 可以执行的操作	默认适用于
ask	内置的只读列表和允许列表中的命令会运行；其他操作都需要等待你批准。	每个新目标
auto	所有命令都会直接运行，无需询问，直到你将模式改回 ask。conn doctor 会对此发出警告。	从不作为默认模式

• 没有任何工具会返回机密、添加活动目标或更改策略。
• 机密通过 stdin 或 SSH 通道的 env 传递，绝不会通过 argv 传递。输出在保存前会经过脱敏处理。
• 远程输出会标记为不可信。Shell 包装命令（sh -c、python -c、sudo……）和 Shell 语法 （;、|、$(...)）始终需要询问。
• conn mcp install 还会禁止 Agent 使用原始的 ssh/scp 和 conn ssh，因此它无法绕过 Conning（pi 没有 权限规则，因此在 pi 中它只会添加服务）。
• 审计日志采用哈希链。它以你的用户身份运行，因此只能做到篡改可检测，无法做到防篡改。

开发

uv sync
uv run pytest --cov=conning      # CI requires 95% coverage on Linux
uv run ruff check && uv run ruff format --check

端到端测试会使用临时的本地 sshd，针对真实的 conn 和 MCP 服务运行（Linux，需要 root 权限来启动；CI 的 e2e 任务会在每次推送时执行此操作）：

eval "$(sudo sh tests/e2e/start-sshd.sh /tmp/conning-sshd | sed 's/^/export /')"
uv run --with keyrings.alt pytest -m e2e   # keyrings.alt: a file keychain for typed passwords

更改 CLI 后，使用 uv run conn help --markdown 更新 README 中的代码块。

文档

• docs/design.md：设计及每项决策的状态。
• docs/blog.html：从最初构想到今天的开发博客。
• docs/manual-test.md：使用临时目标对每项功能进行十分钟检查。
• docs/field-test.md：在实际工作中使用它，以及如何报告妨碍使用的问题。

为什么选择 Python

Python 是最容易在开发者的机器上安装的语言，也是围绕这些机器构建的大多数 AI 工具所使用的语言。uvx conning mcp 无需预先安装即可运行，pip/pipx/uv 也已就绪，而且 MCP SDK、钥匙串绑定和 Agent 客户端都属于同一生态系统。Go 或 Rust 可以生成单个二进制文件，但 Conning 会调用真正的 OpenSSH 二进制文件，并且大部分时间都在等待网络响应，因此它们带来的速度提升在这里作用不大。

许可证

Apache-2.0