zekker6/devsandbox

# devsandbox 为你的 AI 编程助手建立沙箱。运行 Claude Code、Copilot、aider 和其他工具，而无需暴露 SSH 密钥、云凭证或机密信息。 ## 问题所在 AI 编程助手在你的机器上执行 shell 命令、安装软件包并发起网络请求——拥有对你的 `~/.ssh` 密钥、`~/.aws` 凭证、`.env` 机密信息以及所有其他内容的完全访问权限。一个拥有不受限制访问权限的 AI agent 可以读取你的 `~/.ssh/id_ed25519`，通过 API 调用窃取 `~/.aws/credentials`，或者对你的主目录执行 `rm -rf`。 devsandbox 消除了这种风险。它将任何命令包装在一个作用于当前工作目录的沙箱中——你运行 `devsandbox` 的目录将成为具有完全读/写权限的项目根目录，而其之外的所有内容（凭证、密钥、机密信息、其他项目）都会被阻止。可选的代理模式会记录每个 HTTP/HTTPS 请求以供检查。 ## 前置条件 devsandbox 需要 [mise](https://mise.jdx.dev/) 来进行工具版本管理。请在继续之前安装它。 **Linux:** ``` curl https://mise.jdx.dev/install.sh | sh ``` 安装后，在你的 shell 中激活 mise ([设置指南](https://mise.jdx.dev/getting-started.html)): ``` # bash echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc # zsh echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc # fish echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish ``` 此外，你的内核必须支持非特权用户命名空间。请使用以下命令验证： ``` unshare --user true # 应静默成功。如果失败，请参阅 Limitations。 ``` **macOS:** ``` brew install mise ``` 还需要 Docker 运行时（确保在使用 devsandbox 之前它正在运行）： - [OrbStack](https://orbstack.dev/) -- 推荐用于 Apple Silicon（启动最快，资源占用最低） - [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) -- 测试最广泛 - [Colima](https://github.com/abiosoft/colima) -- 免费且开源 ## 快速开始 **安装：** ``` mise use -g github:zekker6/devsandbox ``` **沙箱化你的 AI agent：** ``` # 1. cd 进入你的项目 cd ~/projects/my-app # 2. 在 sandbox 中运行 Claude Code（作用域为 ~/projects/my-app） devsandbox claude --dangerously-skip-permissions # 3. 验证受保护的内容 devsandbox --info ``` devsandbox 对当前工作目录进行沙箱化——先 `cd` 到你的项目，然后运行 `devsandbox`。`devsandbox` 之后的所有内容都会传递给沙箱命令。`--dangerously-skip-permissions` 是一个 Claude Code 标志，用于跳过权限提示——在沙箱内部是安全的，因为 devsandbox 提供了安全边界。 **适用于：** Claude Code、GitHub Copilot、aider、Cursor、Continue、Cline、OpenCode 以及任何基于 CLI 的开发工具。 就是这样。不需要配置文件。在 Linux 上，devsandbox 包含嵌入式二进制文件——零依赖。在 macOS 上，需要 Docker 运行时（参见 [安装详情](#installation-details))。 运行 `devsandbox doctor` 以验证你的设置。 ## 你的 AI Agent 能做和不能做的事 **能做：** 读/写你的项目文件、运行构建命令、安装依赖项、发起 API 调用（在代理模式下会记录日志）。 **不能做：** 读取 SSH 密钥、访问云凭证 (AWS/Azure/GCloud)、读取 `.env` 机密信息、查看其他项目、推送到 git（默认情况下）或修改你的系统。 ### 安全详情 | 资源 | 默认访问权限 | |---|---| | 项目目录 | 读/写 | | `.env` / `.env.*` 文件 | 隐藏（用 `/dev/null` 掩盖） | | `~/.ssh` | 未挂载 | | `~/.aws`, `~/.azure`, `~/.gcloud` | 未挂载 | | `~/.gitconfig` | 已清理（仅限 user.name/email） | | `.git` 目录 | 只读（无提交，无凭证） | | mise 管理的工具 | 只读 | | 网络（默认） | 完全访问 | | 网络（代理模式） | 隔离并记录日志 | | 传出机密（代理 + 脱敏） | 阻止或脱敏 | 一切都是可配置的。详情请参见 [配置](docs/configuration.md)。 ## 功能特性 - **零配置安全** —— SSH 密钥、云凭证、`.env` 文件和 git 凭证默认被阻止 - **你的工具，你的 shell** —— mise 管理的工具、shell 配置、编辑器设置（nvim、starship、tmux）都可以在沙箱内工作 - **MITM 代理** —— 可选的流量检查，支持日志查看、过滤和导出 - **HTTP 过滤** —— 白名单/黑名单域名，或逐一交互式批准请求 - **内容脱敏** —— 扫描传出请求中的机密信息，在它们离开你的机器之前阻止或替换它们 - **跨平台** —— Linux 上使用 [bubblewrap](https://github.com/containers/bubblewrap) 命名空间（亚秒级启动），macOS 上使用 Docker 容器 - **项目隔离** —— 每个项目都有自己的沙箱主目录、缓存和日志 - **Git 模式** —— 只读（默认）、读写（带 SSH/GPG）或禁用 - **桌面通知** —— 沙箱化应用可以通过 XDG Desktop Portal 向主机发送通知（Linux） ## 工作原理 **Linux:** 使用 [bubblewrap](https://github.com/containers/bubblewrap) 创建基于命名空间的隔离。不需要 root 权限，不需要 Docker，不需要系统包——bwrap 和 pasta 二进制文件是嵌入式的。启动时间为亚秒级。 **macOS:** 使用带有卷挂载的 Docker 容器来模拟 bwrap 行为。命名卷提供接近原生的文件系统性能。容器被缓存以实现 1-2 秒的重启。 两个后端都会自动检测你的 shell、工具和编辑器配置，并使它们在沙箱内以只读方式可用。 ## 使用示例 ``` # 交互式 sandbox shell devsandbox # 在 sandbox 中运行任意命令 devsandbox npm install devsandbox go test ./... devsandbox cargo build # 带有流量监控的 AI 助手 devsandbox --proxy claude --dangerously-skip-permissions # 查看 AI 访问的内容 devsandbox logs proxy --last 50 # 实时跟踪流量（在另一个终端中） devsandbox logs proxy -f # 仅限白名单的网络访问 devsandbox --proxy --filter-default=block \ --allow-domain="*.github.com" \ --allow-domain="api.anthropic.com" # 显式选择隔离后端 devsandbox --isolation=docker npm install # 临时 sandbox（退出后移除） devsandbox --rm ``` ## Git 集成 默认情况下，`.git` 以只读方式挂载——你可以查看历史记录、差异和状态，但提交会被阻止，并且不会暴露任何凭证。 | 模式 | `.git` | 提交 | 凭证 | |---|---|---|---| | `readonly` | 只读 | 阻止 | 无 **(默认)** | | `readwrite` | 读写 | 允许 | SSH, GPG, 凭证 | | `disabled` | 读写 | 允许 | 无 | ``` # ~/.config/devsandbox/config.toml [tools.git] mode = "readwrite" # for trusted projects that need push/sign ``` ## 代理模式 —— 监控你的 AI Agent 网络活动 将所有 HTTP/HTTPS 流量通过本地 MITM 代理路由。实时查看你的 AI agent 发出的每个 API 调用，阻止可疑域名，或交互式批准每个请求。 ``` # 启用代理 devsandbox --proxy # 查看日志 devsandbox logs proxy --stats # Summary statistics devsandbox logs proxy --errors # Failed requests only devsandbox logs proxy --json # JSON export for scripting # 交互式请求审批 devsandbox --proxy --filter-default=ask # 然后在另一个终端中： devsandbox proxy monitor ``` 在 Linux 上，代理模式使用 [pasta](https://passt.top/) 进行网络命名空间隔离（嵌入式，无需安装）。在 macOS 上，它使用按会话的 Docker 网络。 有关过滤规则、日志格式和远程日志设置，请参见 [代理模式文档](docs/proxy.md)。 ## 安装详情 **Linux:** 要求： - 启用了非特权用户命名空间的 Linux 内核（验证：`unshare --user true` 应该静默成功） - 不需要系统包（bwrap 和 pasta 二进制文件是嵌入式的） ``` # 选项 1：mise mise use -g github:zekker6/devsandbox # 选项 2：下载二进制文件 curl -L https://github.com/zekker6/devsandbox/releases/latest/download/devsandbox_Linux_x86_64.tar.gz | tar xz sudo mv devsandbox /usr/local/bin/ ``` 要使用系统安装的二进制文件而不是嵌入式的，请在 [配置](docs/configuration.md) 中设置 `use_embedded = false`。 可选系统包（如果嵌入式提取失败时的回退方案）。注意：`passt` 包提供了用于网络命名空间隔离的 `pasta` 二进制文件。 ``` # Arch Linux sudo pacman -S bubblewrap passt # Debian/Ubuntu sudo apt install bubblewrap passt # Fedora sudo dnf install bubblewrap passt ``` **macOS:** 需要 Docker 运行时 —— 选项请参见 [前置条件](#prerequisites)。 **从源码构建：** ``` # 需要：Go 1.22+ 和 Task (https://taskfile.dev/) # 或者使用 mise 安装依赖：mise install task build ``` ## 快速参考 ``` devsandbox # Interactive sandbox shell devsandbox # Run command in sandbox devsandbox --proxy # Enable proxy mode devsandbox --rm # Ephemeral sandbox devsandbox --info # Show sandbox configuration devsandbox doctor # Check installation devsandbox config init # Generate config file devsandbox sandboxes list # List all sandboxes devsandbox sandboxes prune # Remove orphaned sandboxes devsandbox logs proxy # View proxy logs devsandbox logs proxy -f # Follow logs in real-time devsandbox tools list # List available tools devsandbox tools check # Verify tool setup devsandbox image build # Build Docker image (macOS) ``` ## 文档 | 页面 | 内容 | |---|---| | [沙箱机制](docs/sandboxing.md) | 隔离后端、安全模型、文件系统布局、覆盖挂载、自定义挂载、Docker 后端详情 | | [代理模式](docs/proxy.md) | 流量检查、日志查看/过滤/导出、HTTP 过滤、询问模式、内容脱敏、远程日志 | | [工具](docs/tools.md) | mise 集成、shell/编辑器/提示符设置、AI 助手配置、Git 模式、Docker socket 代理 | | [配置](docs/configuration.md) | 配置文件参考、项目特定配置、条件包含、端口转发、凭证注入 | | [用例](docs/use-cases.md) | Shell 别名、自动补全、开发工作流、安全监控脚本 | ## 限制 **Linux (bwrap):** - 需要非特权用户命名空间（有关特定发行版的指导，请参见 [故障排除](docs/sandboxing.md#troubleshooting)） - SELinux 或 AppArmor 可能会限制命名空间操作（参见 [安全模块](docs/sandboxing.md#security-modules)） - MITM 代理可能会破坏具有证书固定功能的工具 - 不支持 GUI 应用程序（无显示服务器转发），但桌面通知可通过 XDG Portal 工作 **macOS (Docker):** - 需要运行中的 Docker 守护进程 - 项目目录访问通过 macOS 虚拟化（VirtioFS/gRPC-FUSE），对于 I/O 密集型操作可能会较慢。沙箱内部操作（npm install、Go 构建）使用命名 Docker 卷，具有接近原生的速度。 - 文件监视（热重载）可能需要轮询模式。解决方法请参见 [文件监视限制](docs/sandboxing.md#file-watching-limitations)。 - 网络隔离使用 HTTP_PROXY 而不是 pasta **两者：** - Docker socket 访问是只读的（无法创建/删除容器）——参见 [工具文档](docs/tools.md#docker) - 无嵌套 Docker（无法在沙箱内运行 Docker） ## 许可证 MIT

标签：Aider, AI安全, AI编程助手, Bubblewrap, Chat Copilot, Claude Code, Copilot, DLL注入, Docker, EVTX分析, HTTP工具, JSONLines, Linux容器, Mise, 凭证保护, 大模型安全, 安全沙箱, 安全防御评估, 开发环境, 文件系统隔离, 日志审计, 沙盒技术, 沙箱, 流量审计, 网络安全, 网络安全, 网络安全审计, 请求拦截, 软件开发, 进程隔离, 隐私保护, 隐私保护, 零信任