Tremelay

Tremelay

本地凭据代理，让 AI Agent 使用你的凭据，而无需接触凭据本身。

你已经赋予 Agent 实际权限：读取这些问题、推送这个分支、调用那个 API。如今，这意味着要把令牌粘贴到配置文件、环境变量或 MCP 服务中，然后祈祷没有东西记录或回显它，也没有东西带着它跑到错误的主机上。

Tremelay 将秘密的持有权与使用它的权限分开。你将凭据保存在本地加密保管库中。每个 Agent 都有自己的身份，以及范围狭窄、会过期且可撤销的授权——“使用此令牌，对 https://api.github.com/repos/you/yourrepo 下的所有内容执行 GET 操作”，“使用此 SSH 密钥，以 git 身份向 git.example.com 验证身份”。Agent 请求 Tremelay 执行操作；Tremelay 使用凭据执行操作，只返回授权允许的结果。Agent 永远不会收到秘密，没有可调用的 getSecret 工具，每次尝试——无论获准还是被拒绝——都会写入哈希链式审计日志。

代理持有秘密。Agent 持有能力。

Agent 可通过 MCP（list_capabilities、describe_capability、invoke_capability）连接，也可通过 ssh-agent 套接字进行 SSH 签名。一切都在本地完成：一个 SQLite 保管库文件、一个仅限用户访问的套接字或命名管道，没有服务、账户或遥测数据。

演示

这是针对一次性保管库的真实会话。秘密是字面字符串 dummy-demo-secret。除 vault create 外，每条命令都会向 stderr 写入一行 vault_unlock id=… result=allowed；此处已删去这些行，仅此而已。

$ tremelay vault create --path demo.db
vault_create id=d8df6f8230cf55a9a8b1b7c7df424f1a result=allowed
vault created

$ CRED=$(tremelay credential put --path demo.db --label "demo api key" --type api_key --secret-file ./secret)
credential_put id=649cee93880ae731b17ea858a439d7fe type=api_key result=allowed reasons=
health_assess id=649cee93880ae731b17ea858a439d7fe type=api_key result=allowed reasons=
649cee93880ae731b17ea858a439d7fe

$ AGENT=$(tremelay agent create --path demo.db --label claude-code)
agent_create agent=3a0f2de100565eb2e4be158fdb9a8201 grant= result=allowed
3a0f2de100565eb2e4be158fdb9a8201

$ GRANT=$(tremelay grant create --path demo.db --agent $AGENT --credential $CRED \
    --operation http_broker --resource https://api.github.com/repos/CharitonMedia/Tremelay \
    --method GET --inject bearer --expires 2030-01-01T00:00:00Z)
grant_create agent=3a0f2de100565eb2e4be158fdb9a8201 grant=a0f8b04d64d8ece4a56130feb2607ce9 result=allowed
a0f8b04d64d8ece4a56130feb2607ce9

$ tremelay capability list --path demo.db --agent $AGENT
capability_list agent=3a0f2de100565eb2e4be158fdb9a8201 grant= result=allowed
{"grant_id":"a0f8b04d64d8ece4a56130feb2607ce9","agent_id":"3a0f2de100565eb2e4be158fdb9a8201","credential_id":"649cee93880ae731b17ea858a439d7fe","operations":["http_broker"],"resource":"https://api.github.com/repos/CharitonMedia/Tremelay","created_at":"2026-10-14T04:20:00.618845291Z","expires_at":"2030-01-01T00:00:00Z","status":"active"}

$ tremelay capability authorize --path demo.db --agent $AGENT --credential $CRED \
    --operation http_broker --resource https://api.github.com/repos/CharitonMedia/Tremelay
capability_authorize agent=3a0f2de100565eb2e4be158fdb9a8201 grant=a0f8b04d64d8ece4a56130feb2607ce9 result=allowed
allowed a0f8b04d64d8ece4a56130feb2607ce9

$ tremelay capability authorize --path demo.db --agent $AGENT --credential $CRED \
    --operation http_broker --resource https://api.github.com/repos/someone/else
capability_authorize agent=3a0f2de100565eb2e4be158fdb9a8201 grant=a0f8b04d64d8ece4a56130feb2607ce9 result=denied_scope
denied_scope

$ tremelay grant revoke --path demo.db --id $GRANT
grant_revoke agent=3a0f2de100565eb2e4be158fdb9a8201 grant=a0f8b04d64d8ece4a56130feb2607ce9 result=allowed
a0f8b04d64d8ece4a56130feb2607ce9

$ tremelay capability authorize --path demo.db --agent $AGENT --credential $CRED \
    --operation http_broker --resource https://api.github.com/repos/CharitonMedia/Tremelay
capability_authorize agent=3a0f2de100565eb2e4be158fdb9a8201 grant=a0f8b04d64d8ece4a56130feb2607ce9 result=denied_revoked
denied_revoked

$ tremelay audit list --path demo.db --agent $AGENT --action capability_authorize
{"seq":12,"time":"2026-10-14T04:20:00.755379639Z","action":"capability_authorize","credential_id":"649cee93880ae731b17ea858a439d7fe","credential_type":"api_key","result":"allowed","agent_id":"3a0f2de100565eb2e4be158fdb9a8201","grant_id":"a0f8b04d64d8ece4a56130feb2607ce9","operation":"http_broker","class":"routine","severity":"info","hash":"bcf38c87bf3038dafc6f1b0c52be3cb6b213cd202096d481370373e3abf847ab"}
{"seq":14,"time":"2026-10-14T04:20:00.821094153Z","action":"capability_authorize","credential_id":"649cee93880ae731b17ea858a439d7fe","credential_type":"api_key","result":"denied_scope","agent_id":"3a0f2de100565eb2e4be158fdb9a8201","grant_id":"a0f8b04d64d8ece4a56130feb2607ce9","operation":"http_broker","class":"expected_denial","severity":"low","hash":"2d2432203b7bbacf562c4f0433090f0647037d746e6d689492c44f25e3b2d2b1"}
{"seq":18,"time":"2026-10-14T04:20:00.951247858Z","action":"capability_authorize","credential_id":"649cee93880ae731b17ea858a439d7fe","credential_type":"api_key","result":"denied_revoked","agent_id":"3a0f2de100565eb2e4be158fdb9a8201","grant_id":"a0f8b04d64d8ece4a56130feb2607ce9","operation":"http_broker","class":"replay","severity":"high","hash":"f8b19ee681e76b1b6fc813116232e732e57644d47ebd3afbefab0a8e23ce2cf1"}

$ tremelay audit verify --path demo.db
84d0bf149dc187c9517fd9a0afce2571fb4fad648cac25ebb5298e5cf68e27a4

两次拒绝操作都以非零状态退出，且没有任何一行包含秘密。密码短语来自 TREMELAY_PASSPHRASE；交互式使用时，则会显示无回显提示。

安装

Tremelay 需要固定版本的 Go 工具链（1.26.9，见 go.mod）；go install 会自动切换到该版本。

go install github.com/CharitonMedia/Tremelay/cmd/[email protected]

克隆仓库后，运行 make build 或 go build -o tremelay ./cmd/tremelay 也能完成同样的操作。使用 tremelay version（或 tremelay --version）检查构建结果。

v1.0.3 版本 包含各平台的压缩包，文件名为 tremelay_<version>_<os>_<arch>.tar.gz（Windows 上为 .zip）。每个压缩包解压后会得到一个名为 tremelay 的二进制文件 （Windows 上为 tremelay.exe），以及 LICENSE、CycloneDX SBOM 和 SHA256SUMS 文件——校验和只能检测下载损坏，无法检测发行包被替换。该版本还为各平台提供一个 MCP Bundle， 文件名为 tremelay-mcp_<version>_<os>_<arch>.mcpb，适用于安装 MCP Bundle 的客户端（见通用 MCP 快速入门）。 v1 尚未对发行包签名。make release-dry 可在本地构建这些制品； 见 ADR 0027。将所需压缩包和 SHA256SUMS 下载到同一目录，然后按文件名校验该压缩包：

grep tremelay_v1.0.3_linux_amd64.tar.gz SHA256SUMS | sha256sum -c - &&
  tar -xzf tremelay_v1.0.3_linux_amd64.tar.gz &&
  ./tremelay version

在 macOS 上，可用 shasum -a 256 -c - 替代 sha256sum -c -。

请指定你下载的文件名。如果对整个列表运行 sha256sum -c --ignore-missing SHA256SUMS，而你的压缩包下载失败、 列表中只有其他文件存在，命令仍会以 0 状态退出。

快速入门

从安装到首次成功调用的复制粘贴式配置，每个客户端各有一个页面： docs/quickstarts/（Claude Code、Codex、Hermes、通用 MCP）。

所有场景的流程都相同。tremelay daemon --vault PATH 会在终端提示你输入密码短语（设置非空的 TREMELAY_PASSPHRASE 可免于提示，但不建议这样做；参见从环境变量获取密码短语），随后在仅限当前用户访问的本地套接字上为 Agent 提供服务；tremelay agent create --token-file FILE 会为每个 Agent 创建独立的 bearer 令牌文件，之后可以通过 tremelay agent token issue|rotate|revoke 管理，无需重新创建 Agent；客户端启动的 stdio 命令为 tremelay mcp --daemon --token-file FILE。执行 tremelay lock、达到空闲超时或进程退出都会将密钥清零。参见无头守护进程指南，或参见本地 stdio MCP，了解每次启动时使用 pinentry 的方式。对于 SSH，tremelay ssh-agent 会发布一个 SSH_AUTH_SOCK，使用始终不会离开守护进程的密钥进行签名。

它不会做什么

在将任何内容托付给它之前，请先阅读本节。

• 仅供一个人使用。 单用户、单个保险库。不支持多用户、组织、共享保险库或团队策略。
• 仅限一台机器。 使用仅限当前用户访问的 Unix 套接字或 Windows 命名管道，以及 stdio；不提供网络或远程 MCP 传输。tremelay ssh-agent 仅支持 Linux 和 macOS，在 Windows 上会安全地拒绝运行。
• Agent 仍会读取代理响应。 http_broker 授权会返回状态码、一组允许列表中的响应标头，以及最多 32 KiB 的响应正文；其中的凭据会以常见编码形式（原始、URL、base64、hex、JSON 转义）进行脱敏。Agent 看不到凭据，但能看到该凭据解锁的数据，而正文中的任何内容都可能包含提示词注入（H1）。无法检测蓄意重新编码或拆分凭据的恶意上游；仅向你信任其可接触凭据的来源授予权限。
• 代理不支持文件上传。 携带 multipart 正文（multipart/form-data，文件上传）的代理请求会被拒绝，并返回 denied_malformed。请改用 JSON 或 urlencoded 表单。
• 已解锁的守护进程信任你的 uid。 在解锁期间，任何以你的身份运行的代码都可以使用已授予你的 Agent 的能力。但它仍无法读取凭据、更改授权或获知你的密码短语，而且它执行的所有操作都会被审计——这就是信任边界。
• 不支持 OAuth 刷新代理、数据库会话代理、浏览器表单填充、TOTP 或由提供方协助的轮换。 这些内容列于 VISION.md 和路线图中，不属于 v1。
• 未经第三方审计。 尚无独立安全审查，也未提供签名版本。审计链对你而言具有防篡改性，但没有其他人会为其创建检查点。
• credential get 会打印原始密钥。 这是供人使用的控制平面，属于有意设计；任何 Agent 接口都无法访问它。
• 旧版 GitHub issue 授权会阻止解锁（H2）。 如果保险库仍保存着 v1 之前的 github_issue_state 授权，在使用 v1 之前的二进制文件撤销该授权前，保险库将无法解锁。

安全

• SECURITY_INVARIANTS.md — 优先于便利性的规则。
• THREAT_MODEL.md — 威胁主体，包括 Agent。
• SECURITY.md — 如何报告漏洞。

文档

ARCHITECTURE.md · VISION.md · ADRs · 保险库生命周期 · HTTP 代理 · SSH 签名 · 经过实测的客户端集成 · v1 包含的内容 · 里程碑历史

tremelay --help 会打印完整的命令列表。

贡献

CONTRIBUTING.md。Apache License 2.0；参见 LICENSE。