cleatdev/cleat

# Cleat [](LICENSE) [](https://github.com/cleatdev/cleat) [](https://github.com/cleatdev/cleat) **运行一切。无损系统。** 在 Docker 沙箱中安全地运行具有完全自主权限的 AI 编程智能体。 一条命令。项目级隔离。主机零风险。 ``` curl -fsSL https://raw.githubusercontent.com/cleatdev/cleat/main/install.sh | bash ``` ``` cd ~/your-project && cleat ``` 就是这么简单。首次运行会构建 Docker 镜像（约 2 分钟），为你的项目启动一个隔离容器，并将你带入具有完全权限的 Claude Code，全部处于沙箱之中。 ``` ┌─────────────────────┐ ┌─────────────────────────────────┐ │ Your machine │ │ Docker container │ │ │ │ │ │ ~/my-project ───────────> │ /workspace │ │ ~/.claude ──────────────> │ /home/coder/.claude │ │ │ │ │ │ Everything else │ │ Claude Code runs free here: │ │ is untouched. │ │ install, build, delete, run │ │ │ │ anything. Fully sandboxed. │ └─────────────────────┘ └─────────────────────────────────┘ ``` ## 系统要求 - **[Docker](https://docs.docker.com/get-docker/)** -- 必须安装并正在运行 - **macOS 或 Linux**（通过 WSL2 支持 Windows） - **一个 [Anthropic](https://www.anthropic.com/) 账户** -- 团队版或 Pro 版 - **git** -- 安装程序使用 ## 为什么选择 Cleat？ ### 问题所在 带有 `--dangerously-skip-permissions` 的 Claude Code 是使用 AI 构建软件的最快方式。没有确认对话框，没有权限提示。Claude 只是执行你的要求。但在你的实际机器上，这意味着： - 系统文件和配置可能被修改或删除 - 软件包可能被安装、升级或全系统移除 - Dotfiles、SSH 密钥或凭证可能被读取或覆盖 - 机器上的其他项目可能被访问或更改 - 一个错误的命令可能导致操作系统无法启动 ### 解决方案 Cleat 为你提供两全其美的方案： | | 无隔离 | 使用 Cleat | |---|---|---| | Claude 可以编辑项目文件 | 是 | 是 | | Claude 可以安装软件包 | 是（在你的系统上） | 是（在容器中） | | Claude 可以运行任何命令 | 是（在你的系统上） | 是（在容器中） | | Claude 可以访问其他项目 | 是 | **否** | | Claude 可以修改你的系统 | 是 | **否** | | Claude 可以读取 ~/.ssh、凭证 | 是 | **否** | | 可以安全地通宵运行 | 否 | **是** | | 文件所有权问题 | 不适用 | **无**（UID/GID 已映射） | | 复制到主机剪贴板 | 是 | **是**（通过剪贴板桥接） | ### 主要特性 - **一条命令** -- `cleat` 构建、启动并运行一切 - **项目级隔离** -- 每个项目都有自己的容器，可并行运行多个项目 - **会话持久化** -- 停止并恢复会话而不丢失上下文 - **适合无人值守使用** -- 让 Claude 通宵工作而不危及你的系统 - **零文件权限问题** -- 容器用户自动匹配你的主机 UID/GID - **共享认证** -- 登录一次，所有容器使用相同的凭证 - **剪贴板支持** -- `pbcopy`、`xclip` 和 `xsel` 垫片通过文件桥接路由到你的主机剪贴板 —— 无需 X11 或特殊终端功能 - **轻量级** -- 基于 Debian-slim 的镜像，包含 Node.js、Python、Git、build-essential、vim、jq 和 socat - **自动升级通知** -- 每天检查一次更新，并在启动 Claude 前通知你 ## 背后的故事 我曾经沉迷于 Vibe Coding。快速发布功能，让 Claude Code 使用 `--dangerously-skip-permissions` 运行，这样它就可以执行任何操作而不打断我的流程。那种体验令人难以置信。我会启动任务，走开，然后回来看到可运行的代码。我在 Mac 上运行多个项目，有时让 Claude 通宵运行，处理大型重构。 然后有一天早上，我打开笔记本电脑，一切都失灵了。系统彻底崩溃。应用程序无法启动，终端无法使用，核心系统文件被修改。Claude 通宵自主工作，在这个过程中，它开始对项目目录之外进行更改。它试图通过修改系统级配置来修复依赖项问题，进而引发了文件系统上一系列更多的“修复”。等它完成时，macOS 已经无法恢复。 我不得不从 Time Machine 备份中恢复整个机器。数小时的设置，重新认证所有内容，重建未备份的本地状态。这一切只是因为我给了 AI 对我实际系统的无限制访问权限。 问题是，我不想停止使用 `--dangerously-skip-permissions`。生产力提升是真实的。没有权限关卡的 Claude Code 是完全不同的体验：它行动迅速，安装所需的东西，运行构建和测试，针对错误进行迭代，所有这些都不需要等你点击五十次“允许”。回到默认权限模式感觉像是重新踩下了刹车。 所以我构建了 Cleat。同样无限制的权力，但在 Docker 容器内部，爆炸半径为零。Claude 可以在沙箱内执行 `rm -rf /`，而我的 Mac 甚至不会察觉。每个项目都有自己的容器，我的主机系统完全未受影响，我永远不必担心我不看的时候 Claude 做什么。 从那以后，我再也没有从备份恢复过。 ## 安装 ### 快速安装（推荐） ``` curl -fsSL https://raw.githubusercontent.com/cleatdev/cleat/main/install.sh | bash ``` 这会将仓库克隆到 `~/.cleat`，检出最新的稳定发布标签，并将 `cleat` 符号链接到你的 PATH。 ### 手动安装 ``` git clone https://github.com/cleatdev/cleat.git cd cleat git checkout "$(git tag -l | grep -E '^v[0-9]' | sort -V | tail -1)" ./bin/cleat install ``` ### 更新 版本发布为 git 标签（例如 `v0.1.0`）。更新器获取标签并检出最新的一个： ``` cleat update ``` 同时也更新容器内的 Claude Code： ``` cleat rebuild ``` ## 入门指南 ### 1. 认证（仅首次） ``` cd ~/your-project cleat # starts the container + launches Claude # 首次运行时 Claude 将提示您登录 ``` 或单独认证： ``` cleat start # start the container cleat login # opens a browser URL to sign in ``` 凭证将保存到主机的 `~/.claude`，并自动在所有容器间共享。登录一次，每个容器都能获取。 ### 2. 使用 ``` cd ~/your-project cleat ``` 就是这样。你已进入具有完全自主权限的 Claude Code，并在 Docker 中沙箱化。 ## 使用方法 ### 日常工作流 ``` # 开始新会话 cd ~/my-project cleat # 恢复上次会话 cleat resume # 检查运行状态 cleat ps # 完成后停止（保留容器以便恢复） cleat stop ``` ### 同时运行多个项目 每个项目都有自己的隔离容器： ``` # 终端 1 cd ~/backend && cleat # 终端 2 cd ~/frontend && cleat # 查看所有运行中的容器 cleat ps ``` ``` Cleat containers: ● cleat-backend-1a2b3c4d Up 12 minutes /Users/you/backend ● cleat-frontend-5e6f7a8b Up 3 minutes /Users/you/frontend ``` ### 命令参考 #### 快速开始 | 命令 | 描述 | |---|---| | `cleat` | 构建 + 运行 + 启动 Claude Code（多合一） | | `cleat resume` | 恢复最近的会话 | #### 生命周期 | 命令 | 描述 | |---|---| | `cleat stop [path]` | 停止此项目的容器（保留以供恢复） | | `cleat rm [path]` | 停止并永久移除容器 | | `cleat stop-all` | 停止所有 Cleat 容器 | | `cleat build` | 构建 Docker 镜像 | | `cleat rebuild` | 强制从头重新构建镜像 | | `cleat clean` | 停止一切并移除镜像 | | `cleat nuke` | 移除**所有**容器、镜像和构建缓存 | #### 交互 | 命令 | 描述 | |---|---| | `cleat claude [path]` | 将 Claude Code 附加到运行中的容器 | | `cleat shell [path]` | 在容器内打开 bash | | `cleat login [path]` | 通过 Anthropic (OAuth) 认证 | | `cleat logs [path]` | 查看容器日志尾部 | #### 信息 | 命令 | 描述 | |---|---| | `cleat status [path]` | 显示容器、镜像和认证状态 | | `cleat ps` | 列出所有 Cleat 容器（运行中和已停止） | | `cleat update` | 检查更新并安装最新版本 | | `cleat version` | 显示当前版本 | 如果省略 `[path]`，所有命令默认为当前工作目录。 ## 工作原理 ### 架构 ``` ┌──────────────────────────────────────────────────────────────┐ │ Your machine │ │ │ │ ~/.claude ──────────────┐ (auth, sessions, settings) │ │ ~/.claude.json ─────────┼── (config) │ │ ~/my-project ───────────┼──────────────────────┐ │ │ │ │ │ │ ┌────────────────────────┼──────────────────────┼───────┐ │ │ │ Docker container │ │ │ │ │ │ v v │ │ │ │ /home/coder/.claude /workspace │ │ │ │ /home/coder/.claude.json │ │ │ │ │ │ │ │ Claude Code (--dangerously-skip-permissions) │ │ │ │ │ │ │ │ Can: read/write project, install packages, run cmds │ │ │ │ Cannot: touch host system, access other projects │ │ │ └───────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ ``` ### 组件 | 文件 | 用途 | |---|---| | `bin/cleat` | CLI 脚本（符号链接为 `cleat`） | | `docker/Dockerfile` | 包含 Claude Code（原生安装程序）的 Debian slim 镜像 | | `docker/entrypoint.sh` | 将主机 UID/GID 映射到容器中，使文件归你所有 | | `docker/clip` | 剪贴板垫片 —— 写入文件桥接（主要）或 OSC 52 守护进程（后备）。符号链接为 `pbcopy`、`xclip`、`xsel` | | `docker/clip-daemon` | 后台守护进程 —— 通过 OSC 52 将剪贴板数据中继到主机终端（支持该功能的终端的后备方案） | | `docker/CLAUDE.md` | Claude Code 的用户级说明（剪贴板用法、粘贴限制） | | `install.sh` | 单行安装程序（`curl \| bash`） | ### 运行 `cleat` 时会发生什么 1. **构建 Docker 镜像**（仅首次） -- 包含 Node.js、Python、Git、build-essential、vim、jq、socat 和 Claude Code CLI 的 Debian slim 2. **启动容器** -- 名为 `cleat--`（哈希值派生自完整项目路径），你的项目挂载在 `/workspace` 3. **映射你的 UID/GID** -- 到容器中，以便 Claude 创建的文件在主机上归你所有 4. **挂载 `~/.claude`** -- 用于所有容器间的共享认证 5. **启动剪贴板桥接** -- 主机端监视器和共享文件挂载，使 `pbcopy`/`xclip`/`xsel` 中继到你的主机剪贴板 6. **启动 Claude Code** -- 在沙箱内使用 `--dangerously-skip-permissions` ### 安全加固 容器默认使用以下保护措施运行： - `--pids-limit 1024` -- 防止 fork 炸弹影响主机 - `--memory 8g` -- 防止失控进程耗尽主机内存 - 入口点中的数字 UID/GID 验证，以防止注入攻击 - 攻击面最小的 Debian slim 基础镜像 ## 自动升级通知 Cleat 每 24 小时通过 `git ls-remote --tags` 检查一次新的发布标签（这是一个不获取任何对象的轻量级网络调用）。当有较新版本可用时，你会在 Claude Code 启动前看到通知： ``` ┌──────────────────────────────────────────────────────┐ │ Update available v0.2.0 → v0.3.0 │ │ Run cleat update to install the latest version. │ └──────────────────────────────────────────────────────┘ ``` - 此检查每天最多运行**一次** —— 不会减慢后续启动。 - 结果缓存在安装目录（`~/.cleat`）内的 `.update_check` 中。 - 该通知仅供参考 —— 绝不会中断或阻止你的工作流。 - 要升级，运行 `cleat update`。要同时更新容器内的 Claude Code，随后执行 `cleat rebuild`。 ## 剪贴板支持 剪贴板开箱即用。当 Claude Code（或任何工具）在容器内调用 `pbcopy`、`xclip` 或 `xsel` 时，文本会被复制到你的**主机机器的剪贴板** —— 无需 X11、显示服务器或特殊终端功能。 ### 工作原理 主机端剪贴板监视器会随每个 Claude Code 会话自动启动。容器通过绑定挂载将剪贴板数据写入共享文件，监视器检测到更改后，使用 `pbcopy`（macOS）、`xclip`、`xsel` 或 `wl-copy`（Linux）将内容复制到你的真实剪贴板。 ``` ┌─────────────────────────────┐ ┌──────────────────────────────┐ │ Docker container │ │ Host │ │ │ │ │ │ Claude Code │ │ │ │ └─ echo "text" | pbcopy │ │ │ │ └─ writes to ────────────> │ /tmp/cleat-clip-*/clipboard │ │ /tmp/cleat-clip/ │ │ └─ watcher detects change │ │ │ │ └─ pbcopy / xclip │ │ │ │ └─ ✔ clipboard! │ └─────────────────────────────┘ └──────────────────────────────┘ ``` 对于支持 [OSC 52](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands) 的终端，还提供了一种后备方案，当文件桥接未激活时自动使用。 ``` # 这些操作都在容器内运行 -- 包括通过 Claude Code： echo "hello" | clip # dedicated helper echo "hello" | pbcopy # macOS-style echo "hello" | xclip -selection clipboard # Linux-style echo "hello" | xsel --clipboard # Linux-style (alternative) git log -1 --format=%B | clip # copy last commit message ``` **限制：** 有效负载上限为 100KB。粘贴（`xclip -o`、`xsel --output`、`pbpaste`）不受支持 —— 剪贴板仅支持复制。 ## 故障排除 ### 剪贴板不工作 如果容器内的 `pbcopy`/`xclip`/`xsel` 没有复制到你的主机剪贴板： 1. **检查桥接是否处于活动状态** -- 在容器内，运行 `ls /tmp/cleat-clip/.host-ready`。如果文件存在，则主机监视器正在运行。 2. **检查主机上的剪贴板命令** -- 监视器需要 `pbcopy`（macOS）、`xclip`、`xsel` 或 `wl-copy`（Linux）在你的 PATH 中可用。 3. **重建容器** -- 如果你是从旧版本升级的，运行 `cleat rm && cleat start` 以创建新的剪贴板挂载。 4. **大有效负载** -- 剪贴板上限为 100KB。对于更大的内容，将其写入 `/workspace` 中的文件并从主机复制。 ### Docker 未运行 ``` Cannot connect to the Docker daemon ``` 启动 Docker Desktop 或 Docker 守护进程，然后重试。 ### 安装时权限被拒绝 ``` # 如果 /usr/local/bin 不可写，安装程序会自动使用 sudo。 # 您也可以安装到自定义位置： ln -sf "$(pwd)/bin/cleat" ~/.local/bin/cleat ``` ### 容器命名 每个容器命名为 `cleat--`，其中哈希值派生自项目的完整绝对路径。这意味着具有相同目录名的两个项目（例如 `~/code/client-a/api` 和 `~/code/client-b/api`）会自动获得独立的容器。每次会话前会打印容器名称，让你始终知道自己身处哪个沙箱。 ### Claude Code 更新后重建 Claude Code CLI 内置于 Docker 镜像中。获取最新版本： ``` cleat rebuild ``` ### 文件以 root 身份创建 这种情况不应发生。入口点映射了你的主机 UID/GID。如果发生了，请检查 Docker 是否正确传递了 `HOST_UID` 和 `HOST_GID`： ``` cleat shell id # should show your UID/GID ``` ## 卸载 ``` cleat clean # remove all containers + image cleat uninstall # remove CLI symlinks rm -rf ~/.cleat # remove the repo clone ``` 你的项目文件和 `~/.claude` 凭证永远不会被触及。 ## 贡献 欢迎贡献！请提交 issue 或 pull request。 ``` git clone https://github.com/cleatdev/cleat.git cd cleat # 在 main 上进行更改，并在本地测试 ./bin/cleat start ~/some-test-project ``` ### 发布 通过在 `main` 上标记 commit 来发布版本： ``` git tag v0.3.0 git push --tags ``` 安装程序和更新程序都会自动解析最新的 semver 标签。不需要发布分支。 ## 许可证 [MIT](LICENSE) _{Cleat — 运行一切。无损系统。| AI 编程智能体的 Docker 沙箱 | cleat.sh}

标签：AI编程助手, Anthropic, CIS基准, Claude Code, DevSecOps, Docker沙箱, MITM代理, MIT许可, Web截图, 上游代理, 主机防护, 代码隔离, 容器安全, 应用安全, 开发环境, 提示词注入, 终端工具, 网络安全研究, 自动化代理, 虚拟化, 请求拦截, 逆向工具, 零信任执行