开发容器中的 Claude Code

一个沙盒化开发环境，可安全启用 bypassPermissions 运行 Claude Code。由 Trail of Bits 为安全审计工作流构建。

为何使用此方案？

在宿主机上使用 bypassPermissions 运行 Claude 存在风险——它可以在不确认的情况下执行任何命令。此开发容器提供了文件系统隔离，让你既能享受无限制 Claude 带来的生产力提升，又不会危及宿主机安全。

适用场景：

• 安全审计：审查客户端代码而不危及宿主机
• 不可信仓库：安全探索未知代码库
• 实验性工作：让 Claude 在隔离环境中自由修改代码
• 多仓库协作：处理多个相关仓库

前提条件

• Docker 运行时（选择其一）：

  • Docker Desktop - 确保其正在运行
  • OrbStack
  • Colima：brew install colima docker && colima start

• 终端工作流（一次性安装）：

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# 停止并删除当前虚拟机（会移除容器/镜像）
colima stop && colima delete

# 使用优化设置启动
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

快速开始

选择适合你的工作流模式：

模式 A：单项目容器（隔离）

每个项目拥有独立的容器及独立卷。适用于一次性审查、不可信仓库，或需在项目间保持隔离的场景。

终端：

git clone <不可信仓库>
cd 不可信仓库
devc .          # 安装模板 + 启动容器
devc shell      # 在容器中打开 shell

VS Code / Cursor：

1. 安装 Dev Containers 扩展：

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. 设置开发容器（选择其一）：

   root@kitploit:~

   # 选项 A：使用 devc（推荐）
   devc .
   
   # 选项 B：手动克隆
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. 在 VS Code 中打开你的项目文件夹，然后：

   • 按下 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux)
   • 输入 "Reopen in Container" 并选择 Dev Containers: Reopen in Container

模式 B：共享工作区容器（分组）

父目录中包含开发容器配置，你在此目录下克隆多个仓库。所有仓库共享卷。适用于客户项目、关联仓库或持续工作。

# 为客户项目创建工作区
mkdir -p ~/sandbox/客户名称
cd ~/sandbox/客户名称
devc .          # 安装模板 + 启动容器
devc shell      # 在容器中打开 shell

# 容器内：
git clone <客户仓库-1>
git clone <客户仓库-2>
cd 客户仓库-1
claude          # 准备开始工作

基于令牌的身份验证（无头模式）

适用于无头服务器或跳过交互式登录向导：

claude setup-token                          # 在宿主机上运行，一次性操作
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # 使用令牌重建容器

令牌会被转发到容器中。每次创建容器时，post_install.py 会执行一次一次性握手，使 claude 启动时无需登录向导。

这解决了 Claude Code 的交互式引导向导在容器中总是显示的问题，即使已有有效凭据（#8938）。

如果你不设置令牌，交互式登录流程仍然有效。

CLI 辅助命令

devc .              在当前目录安装模板并启动容器
devc up             启动开发容器
devc rebuild        重建容器（保留持久卷）
devc destroy [-f]   移除当前项目的容器、卷和镜像
devc down           停止容器
devc shell          在容器中打开 zsh shell
devc exec 命令      在容器内执行命令
devc upgrade        升级容器内的 Claude Code
devc mount 源路径 目标路径  添加绑定挂载（宿主机 → 容器）
devc sync [名称]    将开发容器中的 Claude Code 会话同步到宿主机
devc template 目录  将开发容器文件复制到指定目录
devc self-install   将 devc 安装到 ~/.local/bin

注意： 使用 devc destroy 清理项目的 Docker 资源。手动移除容器（例如 docker rm）会遗留孤儿卷和镜像，导致 devc destroy 无法找到。

会话同步用于 /insights

Claude Code 的 /insights 命令会分析你的会话历史，但它只读取宿主机的 ~/.claude/projects/。开发容器卷内的会话对它是不可见的。

devc sync 将来自所有开发容器（运行中和已停止）的会话日志复制到宿主机，使 /insights 可以包含它们：

devc sync              # 同步所有开发容器
devc sync crypto       # 按项目名称过滤（子字符串匹配）

开发容器通过 Docker 标签自动发现——无需知道容器名称或 ID。同步是增量的，因此可以反复安全运行。

文件共享

VS Code / Cursor

将文件从宿主机拖入 VS Code 资源管理器面板——它们会自动复制到 /workspace/ 中。无需配置。

终端：devc mount

要让宿主机目录在容器内可用：

devc mount ~/drop /drop           # 读写
devc mount ~/secrets /secrets --readonly

这会向 devcontainer.json 添加一个绑定挂载，并重新创建容器。现有的挂载会在 devc template 更新时保留。

提示： 共享的“投放文件夹”对于在不挂载整个家目录的情况下传递文件非常有用。

安全说明： 避免挂载大的宿主机目录（例如 $HOME）。每个挂载的路径在容器内都是可写的，除非指定了 --readonly，这会破坏本项目提供的文件系统隔离。

网络隔离

默认情况下，容器具有完全的外部网络访问权限。为更严格的安全，可使用 iptables 限制网络访问。

何时启用网络隔离

• 审查可能包含恶意依赖的代码
• 审计具有遥测或“回传”行为的软件
• 对高度敏感的审查进行最大隔离

示例：Claude + GitHub + 包仓库

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

权衡

• 阻止包管理器，除非你允许特定仓库
• 可能会破坏需要网络访问的工具
• DNS 解析仍然有效（必要时可考虑阻止）

威胁模型

本项目主要解决的是 Claude Code 在宿主机上运行任意命令 的问题。当启用 bypassPermissions 时，Claude 会执行 shell 命令、安装包、修改文件，而无需确认。在宿主机上，这意味着它可以修改你的 shell 配置、在项目目录外执行 rm -rf，或滥用本地存储的凭据。开发容器将所有操作限制在一个可丢弃的容器中，其爆炸半径仅限于 /workspace。

容器中包含常见的开发工具，因此你可以在其中进行所有开发工作——而不仅仅是运行 Claude。推荐的工作流是：克隆仓库，启动开发容器，然后完全在其中工作。如果你的项目需要额外的运行时或工具，可以将其添加到 Dockerfile 中以备重复使用，或通过 devc exec 临时安装。

关于隔离的具体边界，请参见下面的安全模型。需要特别指出的一点是：开发容器运行时会自动将宿主机的 SSH 代理套接字（SSH_AUTH_SOCK）转发到容器中。这使得容器内的代码可以像你一样通过 SSH 进行身份验证（例如 git push），但实际的私钥材料保留在宿主机上，永远不会暴露给容器。

安全模型

此开发容器提供文件系统隔离，但并非完整的沙箱。

已沙盒化： 文件系统（宿主机文件不可访问）、进程（与宿主机隔离）、包安装（保留在容器内）

未沙盒化： 网络（默认完全出站——见网络隔离）、git 身份（~/.gitconfig 以只读方式挂载）、SSH 代理（套接字转发，密钥保留在宿主机）、Docker 套接字（默认不挂载）

容器会自动配置 bypassPermissions 模式——Claude 无需确认即可执行命令。这在宿主机上会有风险，但容器本身就是沙箱。

容器详情

卷存储在容器外部，因此即使执行 devc rebuild，你的 shell 历史、Claude 设置和 gh 登录状态仍会保留。宿主机的 ~/.gitconfig 以只读方式挂载，用于 git 身份。

故障排除

"devcontainer CLI 未找到"

npm install -g @devcontainers/cli

容器无法启动

1. 检查 Docker 是否运行
2. 尝试重建：devc rebuild
3. 检查日志：docker logs $(docker ps -lq)

GitHub CLI 认证未持久化

gh 卷可能需要修复所有者：

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv 无法工作

Python 通过 uv 管理：

uv run script.py              # 运行脚本
uv add package                # 添加项目依赖
uv run --with requests py.py  # 临时依赖

开发

手动构建镜像：

devcontainer build --workspace-folder .

测试容器：

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh