termada

Termada

为在真实环境中运行的 AI Agent 提供持久化、受策略管控的任务。

Termada 是一个单二进制、本地优先的运行时，位于 AI Agent 与终端之间，既可在本地运行，也可通过 SSH 连接。Agent 通过 Model Context Protocol 与它通信，并获得一套可靠的 工具，而不是原始 Shell：有界等待的 exec_run、保留 cwd/env 的持久会话、输出流式传输的异步任务、用于交互式 提示的 PTY 输入，以及结构化结果；与此同时，你可以通过实时仪表板查看并控制正在运行的任务，使用任务终止开关和审批队列。Mission Control 围绕这些执行过程，增加了持久化目标、由 GPT/Codex 编写的计划、经运行时验证的步骤、中断恢复能力，以及可导出的证据报告。

_{实时仪表板：每个会话都是真实终端，你可以查看并接管——阻止或暂停 Agent，亲自输入内容——同时查看 Agent 面板、策略管理、具有防篡改能力的历史记录，以及用于终止所有活动任务的开关。}

为什么选择 Termada

将原始 Shell 交给 AI Agent，既脆弱又不透明：命令因提示而阻塞，Agent 也会挂起；不同调用之间 cd 和导出的环境变量不会保留；长时间构建会塞满上下文窗口；而你既看不到正在运行的内容，更不用说停止它。Termada 用一个运行时取代原始 Shell，让 Agent 可靠地执行任务，也让你透明地了解执行情况：

• 让 Agent 可靠地执行任务 — 阻塞式 exec_run 调用使用有界等待时限并返回结构化输出；会话会保留 cwd/env；长时间运行的任务以异步方式运行并逐步传输输出，而不是一次性倾倒；交互式提示可以得到响应。
• 让你透明地了解执行情况 — 一个仪表板就能显示每个 Agent 和每个会话对应的真实终端；由 confirm 匹配的受控操作会等待你的审批；一个按钮即可安装短期操作准入屏障，请求取消活动网关执行、向活动引擎任务发送信号并关闭转发；远程/提供商端的影响仍需通过终端验证或协调处理。
• 让任务过程有据可查 — Agent 的计划、实际命令、审批决定、验证任务、结果和审计锚点都保存在一起。计划步骤只有在 Termada 观察到真实任务以零退出码结束后才能通过。

任务控制中心

对于具体的运营目标，Codex 或其他 MCP Agent 会从 mission_create(goal, plan) 开始。Termada 会分配一个专用的持久会话； 常规 exec_* 调用仍使用相同的策略、审批、PTY/SSH 和审计路径。 Agent 会通过 mission_update 附加每个成功的 job_id，然后导出 mission_report。

报告会将运行时观察到的证据与 Agent 备注分开，包含精确的审计序列/哈希锚点， 并返回一个记录在审计日志中的 SHA-256。如果守护进程重启，尚未进入终态的任务会变为 interrupted；mission_resume 会创建一个新的会话尝试，而不会假装 PTY 状态得以保留。

运行隔离的真实执行演示：

./demo/mission-control/run.sh

演示会启动一个故障的环回 HTTP 服务和一个独立的演示守护进程。受保护的修复操作确实会改变服务状态，并等待人工审批； 最终探测必须观察到 HTTP 200。请参阅 demo/mission-control 和 2:40 演示脚本。

功能

执行引擎

• 通过 PTY 建立持久 Shell 会话，在多条命令之间保留 cwd、env 和 venv。
• 异步任务：exec_start → job_id；通过稳定游标增量轮询，并提供连续的有界分页、完整的状态机和结构化错误。
• 回答交互式提示（exec_write，并对机密信息进行脱敏）。本地 PTY 任务支持进程组信号/终止；远程 SSH 中断/终止请求会尽力发送 Ctrl-C，但不保证强制终止。
• 清理输出：有状态的 ANSI/VT 清理、CR 折叠、有界保留，以及尽力进行的机密信息脱敏。

实时控制与可观测性

• 长期运行的守护进程通过 Unix 套接字提供控制平面；serve --stdio 是一个轻量封装，用于将 MCP 代理到该守护进程——因此多个 Agent 共用一个守护进程和一个仪表板。
• Web 仪表板中每个会话都会以真实终端的形式呈现（xterm.js，通过 SSE 流式传输），并支持操作员接管：在任务的 PTY 中输入内容、暂时阻止 Agent 输入，或暂停其输出。
• 工作区标签、有界状态引导、可通过游标恢复的实时更新、 英文控件，以及适配桌面端/移动端的导航。
• 审批队列、活动动态、策略/服务管理，以及用于取消已准入操作、活动引擎任务和转发的全部停止屏障。
• 一个 TUI（termada top）和完整的检查 CLI。
• 同步记录、哈希链式的审计日志，并尽力进行脱敏。termada audit verify 会验证跨轮换分段的连续链。

任务控制中心

• 持久化、按所有者隔离的任务，包含目标、最多 24 个计划步骤、专用会话、多次恢复尝试、有界证据时间线和终态结果。
• 对已完成步骤进行运行时校验（任务会话中的 job_id、 status=exited、exit_code=0），且当仍有任务处于活动状态时拒绝报告成功。
• 以任务为核心的桌面端/移动端仪表板，包含置顶审批、过期/离线状态、紧凑的计划/证据视图，以及 Markdown 报告下载。 安全
• 策略引擎：每个 argv 单词都会进行 shell 引号转义；allow / deny / confirm 匹配会检查前导赋值、绝对路径、Darwin 大小写变体、已知包装器和显式 shell 负载。存在 deny/confirm 规则时，shell 脚本、stdin、交互式 shell 和含糊的复合命令都会默认拒绝。结构化策略还会匹配经过身份验证的主体、租户、类型化操作 / 资源 / 上下文、风险和可逆性。每个经控制且结果为 confirm 的操作都会进入持久化操作员队列，超时后默认拒绝，且只有调用方重试完全相同的已批准操作 ID 时才能执行。
• 一个规范网关覆盖所有公开的副作用路由：重新检查当前策略、消耗一次性审批、原子化预算授权、持久化意图、记录提供方结果，以及显式的 outcome_unknown 对账状态。
• 由策略管理的预算涵盖操作次数、运行时间、金额、工具 / 模型成本、生产环境变更和结果产生后的失败，并支持全局、租户、主体或接收方的精确范围。
• 使用 age 加密的保管库（无 CGO）；保管库 API 绝不会向 Agent 返回密钥值。密钥值由守护进程注入，并注册以便尽力进行输出脱敏。
• 按 Agent 配额并隔离所有者的作业、会话、会话范围内的远程文件操作和转发。每个所有者最多可有 32 个会话和待确认项，总计最多 128 个；每个所有者最多可有 16 个活动转发，总计最多 64 个。本地主机路径仍属于共享的操作系统 / 文件系统边界。在生产环境中设置 security.identity_mode: strict：每个已配置的 Agent 都必须有已存在的已分配策略，并使用唯一的强静态令牌，或显式启用、离线验证且短期有效的 agent_identity JWT 进行身份验证。无令牌、未知身份和无策略的调用方都会默认拒绝。没有结构化规则的严格策略也会拒绝所有未匹配到显式 legacy allow 规则的命令；deny/confirm 门控优先。对于省略该字段的旧配置，development 会保留对受信任本地客户端使用自我声明 ID 的行为，并作为兼容性默认值。
• 可选的 security.run_as 会将本地 shell 进程降权至专用 uid，并禁用由守护进程特权提供的本地文件工具和守护进程环境继承；如需访问本地文件，请使用该降权会话中的命令。远程 SFTP 仍可用。
• 每个 TCP /api/* 请求和 /metrics 都必须使用仪表板令牌，或使用已启用且经固定 JWKS 验证的人类 JWT。仅供操作员使用的 Unix 套接字路由同样需要经验证的人类 JWT，或本地 CLI 使用的独立 cli.token。
• 可选的固定 JWKS 操作员身份会将主体、租户、角色、委派和已验证的 MFA 绑定到审批；策略可以要求角色法定人数、审批人彼此不同且排除请求者。可选的 Ed25519 审计锚定功能会通过持久化 HTTPS 发件箱导出经过签名且已 fsync 的链头。 远程和集群
• 持久化的远程 SSH 会话，支持断线重连：连接断开后会重新拨号并创建一个新 shell，以便会话继续接收新命令。已授权的名称、主机、端口、用户、标签和密钥库引用绑定都会固定，因此修改清单无法将已批准或运行中的会话重定向到其他目标。先前的工作目录和环境变量会丢失；正在执行的作业会变为 orphaned，且不受控制的远程进程可能仍会继续运行。重试前请先验证远程状态。
• 通过名称或标签跨服务器运行 fleet_run，并返回经过尽力脱敏的结构化逐服务器结果。命令必须是非空 argv 数组，且在守护进程全局共享的并发上限（最多五个集群目标）下运行；调用可以请求更低的上限。单次调用最多匹配 256 个目标，返回的结果文本总量最多为 2 MiB。SSH 使用密钥库凭据、ssh-agent 或磁盘上的密钥，并通过串行化且执行 fsync 的 TOFU 主机密钥固定机制处理；如果 known_hosts 文件格式错误，则会拒绝继续。
• 按所有者范围限定的本地到远程端口转发。开启转发须通过策略检查，且只有在启动审计记录持久化后才会保留；监听器仅绑定回环地址，每个转发最多同时处理 64 个连接。

运维

• 崩溃恢复（作业会持久化；运行中的作业恢复后会变为 orphaned）、有界的本地文件系统快照和撤销、桌面通知以及仅出站的 Telegram 通知。
• 类型化适配器 SDK 提供持久化的 prepare → execute → verify → compensate/reconcile 阶段、提供方幂等键、不含机密信息的回执和重启恢复。除非具体提供方适配器定义并证明其语义不变式，否则通用 shell 和插件的执行效果仍不透明。
• 暴露给 Agent 的进程外插件采用 <plugin>.<tool> 形式。插件是受信任的可执行文件，并非安全沙箱；调用须通过策略检查，且只有在启动审计记录持久化后才会启动。
• termada update — 在 Unix 上从 GitHub 发布版本进行有界自更新（必须验证 SHA-256，可选验证 Ed25519 签名校验和、精确成员提取并原子替换）。Windows 会提供明确的手动安装路径，因为运行中的 .exe 无法原子替换。

**尚未支持：**原生 Windows ConPTY 运行时（目前可以交叉编译，但 PTY 和信号处理仍是存根），以及代码签名／公证。

安装

一行命令，无需 Go——下载预构建的 macOS 或 Linux amd64/arm64 二进制文件（经 SHA-256 验证）到 ~/.local/bin：

curl -fsSL https://raw.githubusercontent.com/Islomzoda/termada/main/install.sh | sh

使用 TERMADA_VERSION=vX.Y.Z 固定版本，或使用 TERMADA_BIN_DIR=~/bin 更改安装位置。如果 ~/.local/bin 不在 PATH 中，安装程序会打印需要添加的一行内容。

# Docker (current published image: linux/amd64). Keep the published port on
# host loopback; the image binds 0.0.0.0 only inside its network namespace:
docker run --rm --platform linux/amd64 -p 127.0.0.1:7717:7717 ghcr.io/islomzoda/termada

# Persistent container state runs as uid/gid 10001. A fresh named volume is
# initialized with the image's ownership:
docker run --rm --platform linux/amd64 -p 127.0.0.1:7717:7717 \
  --mount type=volume,src=termada-data,dst=/home/termada/.config/termada \
  ghcr.io/islomzoda/termada

# Homebrew:
brew install Islomzoda/tap/termada

# From source (needs Go 1.26.5+):
TERMADA_FROM_SOURCE=1 ./install.sh
# or:  go build -o ~/.local/bin/termada ./cmd/termada

termada serve                    # start the daemon; prints a tokenized dashboard URL
termada dashboard --open         # print and open a fresh tokenized URL

仪表板引导流程会将令牌存储在浏览器会话存储中，并从地址栏中移除它。本地回环地址上的静态资源是公开的，但每个 TCP /api/* 请求和 /metrics 都需要令牌。旧版 dashboard.local_trust 设置已弃用，且不会绕过 API 身份验证。

将其连接到你的 Agent——这是一项一次性、面向用户的全局操作。每个用户账户只需执行一次，所有项目就会自动获得 Termada；无需将任何内容复制到各个仓库中。

对于 Claude Code，只需运行一条命令：

claude mcp add --scope user termada -- termada serve --stdio

使用其他 Agent（或更喜欢文件配置）？将以下内容添加一次到你的全局 MCP 配置中——参见 .mcp.json.example：

{ "mcpServers": { "termada": { "command": "termada", "args": ["serve", "--stdio"] } } }

就这么简单。从现在起，只需让 Agent 执行终端工作——这些操作都会通过 Termada 进行，你可以实时查看并控制。一个共享守护进程就能服务所有项目和所有 Agent 会话，并统一显示在同一个仪表板上。

配置采用严格校验：未知或不受支持的字段会导致启动失败。写作 ${NAME} 的值会从环境变量中展开；如果引用的变量未设置，则会报错，而不会使用空凭据。在相应变量可用之前，请不要填写可选的凭据字段。

通过 Termada 连接远程服务

如果要让 Agent通过 Termada（可观察、可重新连接、受策略约束）操作远程主机，而不是调用原始 ssh，只需注册一次服务器——之后即可按名称连接，无需 IP 地址，也无需原始 ssh 客户端。

将其添加到 config.yaml（参见 config.example.yaml），然后重启守护进程：

servers:
  - name: prod
    host: prod.example.com        # hostname or IP of your server
    user: deploy
    # auth is OPTIONAL: a vault entry name for a Termada-stored credential.
    # Omit it to try SSH_AUTH_SOCK plus unencrypted ~/.ssh/id_ed25519,
    # id_ecdsa, or id_rsa. Termada does not interpret arbitrary ssh config.
    # auth: prod-ssh-key
    tags: [web]

……或者在仪表板中实时添加（Servers → Add）。确认它已注册：

termada servers          # lists registered servers by name

现在 Agent 可以按名称连接：

• 远程 shell 会话——运行 session_create(target="prod")，然后在该会话中运行 exec_run / exec_start（连接期间状态会保留；连接断开后，Termada 会重新连接并创建一个新的 shell，但孤立的远程进程仍可能继续运行）；
• 在多台服务器上运行一条命令——fleet_run(command=[...], servers=["prod"])（也可以按标签指定）。
• 本地回环 TCP 隧道——port_forward(server="prod", remote_host="127.0.0.1", remote_port=5432)，完成后使用它返回的 ID 调用 port_forward_close 关闭隧道。

让 Agent 真正使用 Termada

Claude Code 和 Cursor 等 Agent 内置了 shell，默认会使用它（也会使用原始 ssh）。以下两项设置可以引导它们使用 Termada：

1. 安装使用技能——安装下面的插件，或使用 skills/termada。它会教 Agent 如何使用这些工具（并引导它将远程操作路由到已注册的服务器，而不是使用 ssh）。

2. 添加项目规则，让 Agent 优先使用 Termada。将以下内容放入 CLAUDE.md（Claude Code）、.cursor/rules（Cursor）或 Agent 的系统提示词中：

   所有 shell 和远程操作都使用 Termada MCP 工具——使用 exec_run / exec_start 执行命令；使用 session_create(target="<server>") 和 fleet_run 操作远程服务器。请勿使用内置 shell 或原始 ssh 客户端： 所有操作都必须通过 Termada 进行，以确保可观察、可重新连接并受策略约束。如果服务器不在 server_list() 中，请让我注册它，而不是回退到 ssh。要获得具体的操作结果， 请从 mission_create 开始，每条命令都使用它创建的会话，将实际成功的作业 ID 关联到计划步骤，并以 mission_report 结束。

/plugin marketplace add Islomzoda/termada
/plugin install termada@termada

命令以 argv 数组（["echo", "hi"]）传递，绝不会以 shell 字符串传递， 因此元字符会按字面处理，除非你显式调用 shell，例如 ["bash", "-lc", "..."]。显式的 shell 负载仍会经过策略检查； 存在拒绝／确认规则时，含糊的复合负载会默认拒绝。

CLI

termada serve [--stdio]              daemon, or the MCP shim
termada dashboard [--open]           print / optionally open the dashboard URL
termada top | status                 live TUI / overview
termada jobs [-f] | sessions         list jobs / sessions
termada logs <job> [-f]              stream a job's output
termada kill <job> | stop            kill one job / signal all admitted work
termada pending                      list human-in-the-loop approvals
termada approve|deny [--reason text] [--ticket id] <action_id>
termada audit [verify]               audit feed / verify active + rotated chain
termada servers | unlock             remote inventory / unlock the vault
termada vault init|set|list|rm|reset manage credentials
termada snapshot create|list|restore local-FS safety net (undo)
termada setup                        install user-scoped Claude MCP config
termada doctor                       health check
termada service install|uninstall|status  run the daemon at login
termada update                       Unix self-update; Windows prints manual path

文档

• docs/SECURITY.md — 威胁模型：保护的内容及未保护的内容。
• docs/ACTION_CONTROL_PLANE.md — 封闭的操作目录与生产环境不变量。
• docs/PLUGINS.md — 编写进程外工具插件。
• docs/PUBLISHING.md — 发布与 MCP 注册流程。
• docs/build-week/SUBMISSION.md — OpenAI Build Week 提交材料包。
• docs/build-week/ARCHITECTURE.md — Mission Control 架构与信任边界。

架构

单个守护进程负责运行时状态；Agent 通过 stdio 垫片连接，仪表板、TUI 和 CLI 中的 运行时检查与受控操作使用同一个守护进程控制平面。由主机所有者执行的维护命令，例如 创建／重置保管库文件、安装、服务注册、自我更新、审计文件验证以及配置编辑，在该 API 之外运行，并仍属于受信任的 OS／部署边界。

cmd/termada            CLI: daemon, shim, inspection/control, vault
internal/engine        sessions, jobs, PTY, status machine, signals, files, recipes
internal/action        immutable Principal + Action + Resource + Context contract
internal/control       authorization, approval, budget, intent and outcome gateway
internal/ledger        durable one-use grants, budgets and export outbox
internal/budget        typed policy-owned budget resolution
internal/adapter       typed prepare/execute/verify/compensate/reconcile SDK
internal/identity      pinned-JWKS human and machine JWT verification
internal/anchor        signed external audit receipts and durable delivery
internal/output        cursor buffers, VT cleaner, redaction
internal/policy        argv allow/deny/confirm classification
internal/vault         age-encrypted credential store
internal/audit         hash-chained tamper-evident log
internal/bus           event bus (observability + durable audit)
internal/daemon        long-lived process: listeners, auth, lifecycle
internal/controlplane  HTTP/JSON control-plane server + client
internal/dashboard     embedded web UI
internal/tui           termada top
internal/fleet         server selection + concurrent aggregation
internal/sshx          SSH runner (vault / agent / key auth, TOFU host keys)
internal/mcp           MCP JSON-RPC stdio server + tools
internal/mission       durable missions, evidence validation, recovery, reports

开发

make vet test    # vet + tests
make race        # tests under the race detector
./demo/mission-control/verify_demo.sh  # real MCP + approval + HTTP 503→200 flow

引擎测试会使用真实的 PTY 和 bash；集群逻辑通过模拟运行器进行单元测试；守护进程 堆栈和 SSH 则通过端到端集成测试进行验证。

许可证

Apache-2.0。