execkit

与内置的 Agent Shell 相比，你还可以获得：

• 在本地、SSH 和 Docker 上使用持久化会话。 cd 和环境变量会在调用之间保留， 每条命令都会返回结构化结果：分开的标准输出和标准错误、 退出代码、耗时、当前工作目录。
• 保护 Agent 上下文的输出。 模型看到输出之前会先对机密信息进行脱敏， 输出预算（tail、head、grep、字符数上限）可防止嘈杂的构建输出淹没 上下文窗口。
• 审计记录、实时查看器和撤销功能。 每条命令都可以写入 JSONL 审计日志；你可以在终端或浏览器中实时查看会话（如上所示），远程会话还可以为 工作区文件创建检查点并进行恢复。

安装

使用 uv 即可零安装。将以下内容添加到你的 MCP 客户端配置中：

{ "mcpServers": { "execkit": { "command": "uvx", "args": ["execkit-mcp"] } } }

或者安装 execkit，并让它为你的客户端打印配置：

pip install execkit-mcp && execkit-mcp setup claude   # or: cursor | gemini | codex | vscode | windsurf

然后运行 execkit-mcp doctor 检查设置。更多选项（预构建二进制文件、 cargo install、从源代码构建）请参阅快速入门。

**状态：**早期 0.x 版本。API 可能会在次要版本之间发生变化。在将其用于任何重要任务之前，请阅读 限制。

适用场景

execkit 可与 Agent 的内置 Shell 或沙箱配合使用，但不能取而代之。当 Agent 需要在远程主机上 或容器内工作、你想记录执行过的操作，或者想撤销远程工作区中的文件更改时，可以使用它。

**Agent 就是对手。**驱动 execkit 的大模型可能会被它读取的任何内容注入提示词，因此 execkit 设有自己的调用方： 命令会在运行之前通过策略防护，机密信息会在输出返回之前进行脱敏，而 SSH 主机密钥发生变化时会明确报错，不会重新连接并遭遇中间人攻击。

flowchart LR
    A([AI agent]) -->|command| F{policy fence}
    F -->|blocked| X([rejected, never runs])
    F -->|allowed| T[transport: local / SSH / Docker]
    T --> O[raw output]
    O --> R[redact secrets, bound output]
    R --> E([structured ExecResult])
    E -.-> A

从 Agent 中使用（MCP）

Agent 可以使用 session_create（local、ssh 或 docker）、session_exec、 session_list 和 session_destroy，以及用于远程撤销的 session_checkpoint / session_checkpoints / session_restore。

状态会在调用之间保留，每个结果都会经过解析，而不是从终端输出中抓取：

// session_exec {"command": "cd /app && npm ci"}   -> { "exit_code": 0, "cwd": "/app" }
// session_exec {"command": "npm run build"}        // cwd is still /app
//   -> { "stderr": "Error: Cannot find module 'webpack'",
//        "exit_code": 1, "duration_ms": 3420, "cwd": "/app",
//        "truncated": false, "timed_out": false }

命令默认在 120 秒后超时（每次调用可通过 timeout_secs 设置，最长 3600 秒）。超时后，execkit 会发送 Ctrl-C 中断命令，并返回 timed_out: true 和退出代码 124。会话会保留其当前工作目录和环境变量。

操作员安全设置（主机密钥验证、密钥目录、审计、会话限制）请参阅 crates/execkit-mcp/README.md。

查看 Agent 的操作

设置 EXECKIT_MCP_AUDIT_DIR，即可记录每个会话。execkit-mcp watch 会在终端中实时显示记录，而 execkit-mcp watch --serve --open 会打开顶部所示的 只读浏览器查看器。

使用 / 搜索转录并在错误之间跳转。	重命名、固定或保留会话，导出会话，或截取屏幕截图。被拦截的命令会以内联方式显示。

将其用作库

[dependencies]
execkit = "0.9"                                           # local + SSH + Docker
# execkit = { version = "0.9", default-features = false }  # local + Docker only (no SSH; no russh/tokio)

use std::time::Duration;
use execkit::{Policy, Session};

fn main() -> Result<(), execkit::Error> {
    let mut s = Session::local()?
        .with_policy(Policy { allow: vec![], deny: vec!["rm".into()] })
        .with_timeout(Duration::from_secs(60));

    let r = s.exec("echo hi; echo err 1>&2; cd /tmp")?;
    // r.stdout == "hi"  r.stderr == "err"  r.exit_code == 0  r.cwd == "/tmp"
    println!("{} (exit {})", r.stdout, r.exit_code);

    let r = s.exec_with_timeout("sleep 30", None, Duration::from_secs(1))?;
    // r.timed_out == true  r.exit_code == 124; the session is still usable
    Ok(())
}

可运行示例：cargo run --example local、 EXECKIT_SSH="user:password@host:22" cargo run --example ssh 和 EXECKIT_DOCKER=<container> cargo run --example docker。

Python

在 Python 中使用相同的会话。pip install execkit（原生绑定，无需 Rust 工具链）：

from execkit import Session

with Session.local() as s:
    r = s.exec("echo hi; echo err >&2; cd /tmp")
    print(r.stdout, r.exit_code, r.cwd, r.stderr)   # hi 0 /tmp err

参阅 crates/execkit-py/README.md。

功能一览

• 持久化、有状态的会话，支持 本地 PTY、SSH 或 Docker。SSH 支持使用 ~/.ssh/config 中的主机别名。
• 结构化的 ExecResult：分离 stdout/stderr、退出代码、耗时、工作目录、 truncated、timed_out。
• Base64 命令封装。 注释、heredoc、!、尾随的 &、语法 错误和长命令都不会导致会话挂起。
• 超时后保留会话。 命令超时后会被中断，会话继续运行。
• 机密信息脱敏：常见令牌格式（AWS、GitHub、GitLab、Slack、Stripe、 Google、Anthropic、OpenAI、JWT、PEM 私钥）、URL 密码、 password=/token= 样式的键值对，以及会话赋给机密名称变量的值。回显的命令也会脱敏。
• 输出预算：按行截取 tail/head/head+tail，带上下文的 grep 过滤器， 以及字符数上限。可按调用设置，也可设为会话默认值；结果会报告保留了哪些内容。
• 撤销 Agent 操作（远程会话）：为工作区创建快照，并在命令出错时还原文件（远程端需要 git，且必须显式指定工作区；仅针对文件，不包括副作用）。
• 审计日志和实时查看器，以及向客户端发送的实时 MCP 通知。
• 可嵌入，而非服务：在你自己的进程中运行 cargo add；无需守护进程，也不依赖供应商。

升级到 0.9

相较于 0.8 的破坏性变更。详情请参阅 升级到 0.9。

• SSH 主机密钥固定在 ~/.execkit/known_hosts，而非 ~/.ssh/known_hosts。 不会读取旧的固定记录。首次连接时会重新固定；也可以使用以下命令将其复制过去： mkdir -p ~/.execkit && chmod 700 ~/.execkit，然后运行 grep -E '^[^ ]+ SHA256:' ~/.ssh/known_hosts >> ~/.execkit/known_hosts。 旧的固定记录以不论端口为何的裸主机名作为键：对于非 22 端口，请将行改写为 [host]:port，否则之后连接该主机的 22 端口时会因密钥不匹配而失败。
• 每条命令的 stdin 都是 /dev/null，并且分页器设为 cat。
• 目标端需要 base64。
• 超时会返回退出代码 124，并将 timed_out 设为 true，同时保留会话， 而不是返回错误并关闭会话。ExecResult 新增了 timed_out 字段。
• 会话 ID 的格式为 a3f9-1_local，而非 1_local。
• SshConfig 新增了 connect_timeout 字段（默认 15 s）。请使用 SshConfig::new。

限制

• 不是沙箱。 命令策略采用建议性的字符串匹配，很容易绕过：deny: ["curl"] 会阻止 curl，但不会阻止 env curl、sudo curl 或 sh -c curl。真正的控制手段是最小权限的环境：以最小权限运行 Agent 和 SSH 用户。
• 不支持交互式输入。 stdin 为 /dev/null，因此提示、REPL 和编辑器都无法使用。请使用非交互式标志（sudo -n、apt-get -y）。分页器默认使用 cat，但直接运行 less 或 vim 会一直挂起，直到超时并关闭会话。Shell 历史记录已关闭。
• 超时会中断命令，但不会终止所有进程。 execkit 会发送 Ctrl-C。忽略 Ctrl-C 的命令会结束会话。对于长时间运行的任务，请将其放到后台运行（nohup CMD > /tmp/job.log 2>&1 &），然后轮询日志。
• 目标环境需要 POSIX shell 和 base64。 本地会话使用 bash。 不支持 Windows。
• 核心为同步式。 足以满足典型的 Agent 使用需求，但未针对数千个并发会话进行调优。
• SSH AcceptAny 主机密钥模式可用于测试，但必须显式选择不安全选项。 切勿在生产环境中使用。

发现问题？提交 issue。

贡献与安全

• 贡献：参见 CONTRIBUTING.md。
• 发现漏洞？请遵循 SECURITY.md。请勿为安全报告创建公开 issue。

许可证

Apache-2.0：可自由嵌入，包括用于商业用途。请参见 LICENSE 和 NOTICE。