Claude Code CubeSandbox 集成实战用 PreToolUse Hook 实现透明 MicroVM 隔离的 Bash 执行【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox导读本文基于 CubeSandbox 仓库中的 claude-code-integration 示例讲解如何让 Claude Code 继续运行在宿主机上却把它发出的每一条 Bash 命令透明转发进隔离的 CubeSandbox MicroVM 执行文件编辑留在本地、shell 命令跑在独立内核/文件系统/网络里模型完全感知不到沙箱层也不需要改变任何使用方式。读完本文你将掌握 hook 的安装配置、改写与执行两个核心脚本的工作原理、按会话复用沙箱与 shell 状态持久化的机制、宿主项目只读挂载的约束以及完整的安全设计要点和排错方法。Claude Code(宿主机) ├── Read / Write / Edit ─────────────► 宿主机项目文件 │ └── Bash ──► PreToolUse hook ──► cubesandbox_exec ──► CubeAPI ──► MicroVM (cubesandbox_rewrite.py) (:3000) └─ 按会话复用为什么用 PreToolUse Hook 而不是 MCP / SDK基于 MCP 或 SDK 的沙箱方案依赖 agent主动选择沙箱工具一条普通的Bash调用仍会落到宿主机上。PreToolUsehook 堵住了这个缺口它在工具调用执行之前拦截工具调用本身因此对 Bash 而言隔离是透明且完整的——没有任何命令能绕过它。特性行为透明模型发起普通的Bash调用由 hook 改写。无需改 prompt 或工具。按会话复用沙箱每个 Claude Codesession_id复用一个 MicroVM同一会话的命令共享状态。shell 状态延续同一会话内cd和导出的环境变量在多次 Bash 调用间保留。只读挂载宿主项目会话首次调用可把项目按相同路径只读挂载沙箱命令可读取不可修改宿主文件。fail-closed若无法安全改写hook 以非零退出阻断命令而不是放它到宿主机执行。防注入原命令作为单个shlex引用参数传入shell 元字符和换行都无法越出到宿主机。无条件改写每条 Bash 调用都会被改写已包裹的执行器调用若再次经过 hook只会在沙箱内失败绝不会落到宿主机。自动批准hook 对改写后的 Bash 调用返回permissionDecision: allowClaude Code 的逐命令确认提示被抑制请相应使用--permission-mode/ hooks 策略。从源码结构看cubesandbox_rewrite.py对 payload 的改写逻辑在 examples/claude-code-integration/hooks/cubesandbox_rewrite.py 中实现cubesandbox_exec.py承担执行与状态管理二者通过install.sh注册进~/.claude/settings.json。前置条件运行中的 CubeSandbox 部署CubeAPI 可达如http://127.0.0.1:3000运行 Claude Code 的宿主机上有 Python 3.9一个用于创建沙箱的 CubeSandbox 模板cubemastercli tpl list可列出可用模板快速开始1 —— 安装依赖并配置python3 -m pip install -r requirements.txt cp .env.example .env # 编辑 .env设置 CUBE_API_URL 和 CUBE_TEMPLATE_ID.env中的核心配置项及其说明见 .env.example变量说明默认值CUBE_API_URLCubeAPI 的 base URLSDK 通过它访问控制面http://127.0.0.1:3000CUBE_TEMPLATE_IDhook 创建沙箱使用的模板 ID必填缺失时执行器报CUBE_TEMPLATE_ID is not set无CUBE_SANDBOX_USER沙箱内执行命令的用户rootCUBE_SANDBOX_TIMEOUT沙箱存活 TTL秒1800CUBE_EXEC_TIMEOUT单条命令执行超时秒120CUBE_HOOK_STATE_DIR会话→沙箱映射状态目录~/.cache/cubesandbox-hookCUBE_PROXY_NODE_IP/CUBE_PROXY_PORT_HTTP/CUBE_SANDBOX_DOMAIN远程/自建部署下的 envd 路由覆盖可选空其中CUBE_SANDBOX_USER、CUBE_SANDBOX_TIMEOUT、CUBE_EXEC_TIMEOUT、CUBE_HOOK_STATE_DIR在 cubesandbox_exec.py 中通过环境变量读取且CUBE_SANDBOX_TIMEOUT/CUBE_EXEC_TIMEOUT必须是正整数/正有限浮点数否则执行器以BootstrapError拒绝启动。2 —— 安装 hookcd hooks ./install.sh安装脚本install.sh会把cubesandbox_rewrite.py与cubesandbox_exec.py复制到~/.claude/hooks/权限 0755将 hook 注册进~/.claude/settings.json的hooks.PreToolUse下的Bashmatcher 分组不覆盖你其它设置只把../.env里白名单内的CUBE_*值复制进 hook 配置cubesandbox.env权限 0600provider API key如ANTHROPIC_AUTH_TOKEN、OPENAI_API_KEY不会被写入 hook 配置。重启 Claude Code 以加载 hook。3 —— 照常使用 Claude Code直接用 Claude Code。它发出的每条 Bash 命令现在都在 MicroVM 内执行 执行 uname -a whoami告诉我它在哪运行命令在沙箱里运行不同内核、沙箱用户而 Claude Code 的文件编辑仍在你的宿主机上。工作原理1. 改写阶段cubesandbox_rewrite.pyhook 接收PreToolUseJSON payload。对Bash调用它把tool_input.command改写为python hooks/cubesandbox_exec.py --sessionid --mountcwd --timeout秒 -- 原命令并通过updatedInput返回。关键实现细节cubesandbox_rewrite.py原命令是单个引用参数经shlex.join引用里面的 shell 元字符和换行无法在宿主机执行--分隔符保证以-开头的命令不会被误解析为执行器参数session_id 复用从 payload 的session_id字段取值缺失时回退到default超时透传有校验仅当timeout是正有限数值且不超过MAX_TIMEOUT_MS1 小时时才追加--timeout非法值0、负数、nan、inf、字符串等一律不转发fail-closedpayload 不是 JSON 对象、tool_name缺失或tool_input非法时hook 打印错误并以退出码 2阻断命令绝不放行到宿主机非 Bash 工具原样放行Read/Write/Edit等返回None不产生任何改动无条件改写即使命令文本本身就是执行器调用例如从 transcript 粘贴回来也照常包裹——它只会在沙箱内失败沙箱内不存在宿主 hook 路径绝不会落到宿主机。这些行为在 test_cubesandbox_rewrite.py 中有系统化验证包括控制操作符保持为单个引用参数、session_id/cwd中的注入字符被隔离、非法 payload 被拒绝、超时边界校验以及“仅命名执行器脚本也必须被包裹”等测试用例。2. 执行阶段cubesandbox_exec.py执行器cubesandbox_exec.py按session_id复用一个沙箱会话映射状态存放在~/.cache/cubesandbox-hook/可用CUBE_HOOK_STATE_DIR覆盖session_id 经 SHA-256 哈希作为文件名状态目录权限 0700、状态文件权限 0600并用每会话文件锁fcntl.flock保护并发重用或新建优先通过Sandbox.connect(sandbox_id)重连已缓存的沙箱失败自动回退新建首次调用时通过Sandbox.create(TEMPLATE_ID, ...)创建并记录sandbox_id与随机state_tokenshell 状态延续每条命令被包裹进一段状态包装脚本_state_shell——恢复上次持久化的 cwd 与环境变量运行原命令再把pwd和export -p写回状态文件。其中BASH_ENV、ENV、LD_PRELOAD、PROMPT_COMMAND等会自执行恶意代码的变量被显式清洗返回结果命令结束后缓冲返回 stdout/stderr 与退出码非流式并将退出码透传给 Claude Code串行执行同一会话内并发的 Bash 调用经每会话锁串行执行——一次只跑一条不并行。沙箱 SDK 侧的支撑Sandbox与Config来自 sdk/python/cubesandbox/sandbox.pyConfig的api_url/template_id等字段均可通过环境变量注入见 sdk/python/cubesandbox/_config.py与 hook 的.env白名单机制一一对应。宿主项目挂载会话的首次 Bash 调用可把 Claude Code 的项目目录按相同绝对路径只读挂载进沙箱——沙箱命令可读取宿主项目文件但不能修改或往里写构建产物。挂载请求以host-mountmetadata 形式传入Sandbox.create见 cubesandbox_exec.py[{hostPath: /path/to/project, mountPath: /path/to/project, readOnly: true}]注意挂载的生效条件hostPath在被调度到的 Cubelet 节点上解析而非运行 Claude Code 的机器。因此只有当 Claude Code 与该 Cubelet 同机、或项目已经以相同绝对路径存在于每个可调度 Cubelet 上时这种共享视图才成立。hook绝不会把本地项目上传或同步到远端部署——不要把一个仅客户端存在、在 Cubelet 上可能指向无关数据的路径加入白名单。项目路径必须被 CubeMaster 允许extra_conf: allowed_host_mount_prefixes: - /data/shared/ - /home/you/projects/若挂载被拒执行会回退到无挂载的隔离沙箱Bash 仍然隔离但不再与 Claude Code 宿主侧文件工具共享文件视图。回退时会打印警告[cubesandbox-exec] warning: read-only host mount /xxx was rejected (...); creating a sandbox without the mount重置与卸载# 丢弃某会话绑定的沙箱下次调用重新创建 python3 ~/.claude/hooks/cubesandbox_exec.py --reset --session session-id # 从 ~/.claude/settings.json 移除 hook cd hooks ./install.sh --uninstall--reset会尽力 kill 已缓存的沙箱并清空该会话的状态即使 API 不可达状态也会被清除避免会话被卡死并回收累积的锁文件卸载则从 settings.json 移除 Bash matcher 分组、删除已安装的 hook 文件并保留~/.cache/cubesandbox-hook中的既有状态供用户自行处置。目录结构claude-code-integration/ ├── hooks/ │ ├── cubesandbox_rewrite.py # PreToolUse hook把 Bash 改写为沙箱执行 │ ├── cubesandbox_exec.py # 执行器按会话复用 MicroVM 状态持久化 │ └── install.sh # 幂等安装 / 卸载 ├── tests/ │ ├── conftest.py │ ├── test_cubesandbox_rewrite.py │ ├── test_cubesandbox_exec.py │ └── test_hook_install.py ├── requirements.txt ├── .env.example ├── TROUBLESHOOTING.md ├── README.md └── README_zh.md # 本文件测试python3 -m pip install -r requirements.txt pytest pytest tests测试覆盖了三个层面改写 hook 的注入防护与 fail-closed 行为test_cubesandbox_rewrite.py、执行器的会话复用/状态持久化/并发串行化/超时处理test_cubesandbox_exec.py以及安装脚本的幂等性、配置白名单与卸载还原test_hook_install.py。其中值得关注的安全验证包括状态文件拒绝符号链接、BASH_ENV等自执行变量被清洗、同会话并行调用严格串行max_active_commands 1、安装脚本不向 hook 配置泄漏 provider API key。排错现象可能原因处理Bash 命令仍在宿主机执行hook 未注册 / Claude Code 未重启重新执行hooks/install.sh并重启 Claude CodeCUBE_TEMPLATE_ID is not set.env缺模板设置CUBE_TEMPLATE_ID见cubemastercli tpl list然后重新运行hooks/install.shthe cubesandbox SDK is required未装依赖pip install -r requirements.txt需要cubesandbox与python-dotenvTemplate not found模板 ID 错误检查cubemastercli tpl list挂载被拒警告路径不在allowed_host_mount_prefixes在 CubeMasterextra_conf加前缀或接受无挂载回退更多详细踩坑记录包括模板快照与 CPU 特性绑定导致的CpuidCheckCompatibility报错及其重建方法、npm/pip 安装类命令超时的参数调优等见 TROUBLESHOOTING.md。安全设计要点fail-closedhook 无法安全改写时以非零退出阻断命令绝不放行到宿主机防注入原命令作为单个shlex引用参数传入执行器shell 元字符和换行无法越出无条件改写每条 Bash 调用都会被改写已包裹的执行器调用若再次经过 hook只会在沙箱内失败沙箱内不存在宿主 hook 路径绝不会落到宿主机自动批准hook 对改写后的 Bash 调用返回permissionDecision: allowClaude Code 的逐命令确认提示被抑制请相应使用--permission-mode/ hooks 策略凭据不外泄安装脚本只复制白名单CUBE_*值不会把 provider API key 写进 hook 配置状态文件防护会话状态目录与文件分别以 0700/0600 权限创建读写均拒绝符号链接持久化环境会清洗BASH_ENV/ENV/LD_PRELOAD/PROMPT_COMMAND等自执行变量见 cubesandbox_exec.py 与其测试。这套方案的核心价值在于它不要求模型学习任何新工具或新 prompt而是在 Claude Code 的工具调用边界上做了一层透明的强制隔离——Bash 永远进沙箱文件操作留在宿主机二者互不越界。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考