cottage

cottage 是一款 GitOps 工具，供团队在 git 仓库中管理 age 加密的机密信息。

它提供了一套简单的工作流，用于加密/解密机密、管理接收者，并将机密排除在仓库之外，同时仍能通过 VCS 轻松共享。cottage 还会为加密机密生成脱敏预览，以提高可见性，并支持持久化和临时解密工作流，同时确保机密绝不会以明文形式提交。

1. 功能特性
2. 安装
3. 编辑器集成
   1. VS Code 扩展
   2. Cursor 和 Eclipse 扩展
   3. Vim 插件
4. AI 代理集成
   1. Claude Code 集成
   2. GitHub Copilot 集成
   3. Codex 集成
   4. Antigravity (agy) 集成
   5. Cursor 集成
5. 快速开始
6. GitOps
7. Git 钩子
8. 访问控制
   1. 规则
   2. 验证
9. 任意提供者作为上游
   1. 示例插件
10. 与任意设备同步
11. 了解更多
12. 故障排查
13. 对比
    1. age 与其他加密方案
    2. cottage 与 SOPS
    3. cottage 与 dotenvx
    4. cottage 与 agebox

功能特性

• 防泄露：利用 Rust 的类型系统确保 bug 绝不会意外泄露机密。
• 团队友好：在仓库中共享公钥（接收者），将私钥（身份）保留在本地。
• 访问控制：简单的允许/拒绝规则，控制哪些机密为哪些接收者加密。
• 管理 .gitignore：自动更新 .gitignore，将未加密的机密排除在仓库之外。
• 预览：为加密机密生成带时间戳的脱敏预览，以提高可见性。
• 丰富的差异：保持 git diff 干净且易于审查，同时 ctg diff 显示本地修改的机密与已跟踪的加密对应文件之间的差异。
• 校验和验证：通过验证加密机密和接收者列表与元数据是否匹配，防止篡改。
• Git 钩子：轻松设置 git 钩子，在提交前自动检查/加密机密，并在检出后解密。
• 持久化机密工作流：ctg decrypt/sync 将解密后的机密保留在磁盘上。
• 智能清理生命周期：ctg run（快捷方式 ctgx）和 ctg edit 在操作前解密机密，如果之前已存在则保留在磁盘上，否则在操作后自动清理。
• 完成后清理：ctg encrypt --clean、ctg run --clean 和 ctg edit --clean 确保即使解密文件之前已存在，也会从磁盘上清理掉。
• 环境变量注入工作流：ctg env 将解密后的机密作为环境变量注入以运行命令，完全不写入磁盘。
• 安全的机密管道：ctg cat PATH 在内存中解密并打印到 stdout，以便直接通过 stdin 管道传递给其他工具。
• 清理：ctg clean 从本地仓库删除所有解密后的机密，让你运行 AI 代理时少一分担忧。
• 支持 jj 和非 git 目录：ctg init 可将任意目录变为机密存储库。
• 与任意提供者同步：让你配置任何具有 API 的提供者作为上游，并像 git pull/diff/push 一样开始使用 ctg pull/diff/push。
• 与任意设备同步：使用 cottage 加密并在 git 仓库中管理的机密，可通过 Cottage Sync 在设备间同步。

安装

# rust: cargo-binstall/cargo
cargo binstall --locked cottage
cargo install --locked cottage

# python: pip/uv/uvx
pip install cottage
uv pip install cottage
uvx --from cottage ctg --version

# node: yarn/pnpm/npx
yarn global add @sayanarijit/cottage
pnpm add -g @sayanarijit/cottage
npx -p @sayanarijit/cottage ctg --version

也可作为 docker 镜像使用：

# Docker
docker run --rm -v $PWD:/app sayanarijit/cottage --version

# Podman
podman run --rm -v $PWD:/app quay.io/sayanarijit/cottage --version

或从 GitHub 下载最新版本。

编辑器集成

VS Code 扩展

使用 Cottage VS Code 扩展来安装 ctg、添加 Copilot 安全钩子、从资源管理器加密文件，并通过编辑器工作流打开 .cott.age 文件。

从 Visual Studio Marketplace 安装，或从 vscode-plugin-cottage 本地构建并安装。

Cursor 和 Eclipse 扩展

下载 VSX 文件并在你的 Cursor 或 Eclipse IDE 中安装。其工作方式与 VS Code 扩展类似。

Vim 插件

使用 cottage.vim 插件从 Vim 或 Neovim 加密/解密机密。

AI 代理集成

以下所有集成都会阻止 AI 代理直接运行 ctg/ctgx，以及查看或编辑机密文件：.cottage/ 内的任何内容、任何 *.cott.* 文件（加密的 *.cott.age 二进制块和脱敏的 *.cott.toml 预览），以及磁盘上仍存在 *.cott.age 对应文件的任何已解密文件。

Claude Code 集成

如果你使用 Claude Code，请将 .claude/settings.json 和 .claude/hooks/deny-secrets.py 添加到含有密机的仓库中，以便 Claude Code 会话安全地处理机密，或安装 claude-plugin-cottage 插件。

GitHub Copilot 集成

如果你在 VS Code 中使用 GitHub Copilot，请将 .github/hooks/ctg-policy.json 和 .github/hooks/scripts/deny_ctg_command.py 添加到含有密机的仓库中，以便 Copilot 会话清理解密文件、阻止直接的 ctg shell 命令，并阻止访问机密文件，或安装 vscode-plugin-cottage 扩展以从 VS Code 进行设置。

VS Code 也会加载 .claude/settings.json 钩子定义。如果你在同一仓库中同时保留 Claude 和 Copilot 钩子文件，请确保不要意外运行两次相同的清理钩子。

Codex 集成

如果你使用 Codex，请将 .codex/hooks.json 和 .codex/hooks/deny-ctg.py 添加到含有密机的仓库中，以便 Codex 会话安全地处理机密，或安装 codex-plugin-cottage 插件。

Codex 要求本地钩子在运行前经过审查。添加文件后，在仓库中启动 Codex 并使用 /hooks 审查并信任项目钩子。

Antigravity (agy) 集成

如果你使用 Antigravity（agy），请将 .agents/hooks.json 和 .agents/scripts/deny-ctg.py 添加到含有密机的仓库中，以便 Antigravity 会话安全地处理机密，或安装 agy-plugin-cottage 插件。

Cursor 集成

如果你使用 Cursor，请将 .cursor/hooks.json、.cursor/hooks/deny-ctg.py、.cursor/hooks/deny-read-secrets.py、.cursor/rules/deny-ctg.mdc 和 .cursorignore 添加到含有密机的仓库中，以便 Cursor 会话安全地处理机密。

Cursor 要求先启用钩子。打开 Cursor 设置 > 钩子并启用钩子，然后重启代理会话以使项目钩子生效。.cursorignore 还会将机密文件排除在 Cursor 的索引和代理上下文之外。

快速开始

初始化项目：

mkdir project && cd project

git init  # Optional, cottage works better with git but it's not required
ctg init  # Sets up the .cottage directory and necessary files