CubeSandbox 集成 Pi Coding Agent 实战指南：镜像构建、密钥注入、出网管控与会话持久化

CubeSandbox 集成 Pi Coding Agent 实战指南镜像构建、密钥注入、出网管控与会话持久化【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox在 CubeSandbox MicroVM 中运行 Pi coding agent 与配套示例examples/pi-agent-integration的完整实现覆盖模板镜像构建、注册、宿主端驱动配置、直连与保险柜两种密钥注入方式、基于快照的 pause/resume 会话持久化、出网管控与排错并结合源码级细节展开让读者能端到端复现一套秒起、隔离、密钥不落盘的编码 Agent 工作流。集成对象与版本组件版本Pi coding agentearendil-works/pi-coding-agent通过--build-arg PI_VERSIONx.y.z固定Node.js24通过 NodeSource 安装CubeSandbox 基础镜像ghcr.io/tencentcloud/cubesandbox-base:2026.16E2B SDK宿主端驱动e2b最新CubeSandbox 平台 0.3.0pause/resume/ 0.4.0CubeEgress 密钥保险柜宿主端驱动脚本的依赖声明在examples/pi-agent-integration/requirements.txte2b2.4.1直连与 pause/resume 脚本使用 E2B 兼容接口、cubesandbox0.3.0保险柜方式使用原生 SDK 的出网策略 API、httpx0.27.0warmup 方案的 HTTP 驱动、python-dotenv1.0.0读取.env。为什么要把 Pi 放进沙箱Pi 是一个会编辑文件、执行命令、安装依赖的终端 Agent。直接跑在开发机上Agent 的爆炸半径就等于你的开发环境。放进 CubeSandbox 你能拿到关注点CubeSandbox 提供隔离每个会话一个 KVM MicroVM独立 guest kernel可复现每次会话都从同一个 template 快照启动秒起冷启动 60msN 路并行代价极小长任务sandbox.pause()对 VM rootfs 打快照稍后恢复密钥卫生CubeEgress 在链路上注入鉴权头VM 看不到真实密钥出网审计每次访问 LLM API 都会记入出网审计日志前置条件已部署 CubeSandboxCubeAPI 可访问http://node:3000。cubemastercli已在$PATH且已连通集群。构建机装有 Docker且 registry 能被 Cube 集群拉取。一个 LLM provider 的 API Key。默认 Anthropic任何 Anthropic 兼容或 OpenAI 兼容端点均可通过ANTHROPIC_BASE_URL/ provider 环境变量。Python 3.10宿主端驱动脚本。集成步骤1. 构建模板镜像镜像在cubesandbox-base上叠加 Node.js 24 与 Pi CLIenvd 已监听:49983。完整实现见examples/pi-agent-integration/Dockerfile# examples/pi-agent-integration/Dockerfile ARG CUBE_BASE_IMAGEghcr.io/tencentcloud/cubesandbox-base:2026.16 FROM ${CUBE_BASE_IMAGE} ARG DEBIAN_FRONTENDnoninteractive ARG NODE_MAJOR24 ARG PI_VERSION0.80.3 RUN apt-get update \ apt-get install -y --no-install-recommends \ bash ca-certificates curl git gnupg jq less procps \ python3 python3-pip ripgrep \ curl -fsSL https://deb.nodesource.com/setup_${NODE_MAJOR}.x | bash - \ apt-get install -y --no-install-recommends nodejs \ rm -rf /var/lib/apt/lists/* # 把 Pi 单独放在一层升级 PI_VERSION 只重建这一层 # 不会使慢速的 OS Node.js 层失效 RUN npm install -g --ignore-scripts earendil-works/pi-coding-agent${PI_VERSION} \ pi --version \ npm cache clean --force \ rm -rf /root/.npm ENV PI_CODING_AGENT_DIR/root/.pi/agent \ PI_CODING_AGENT_SESSION_DIR/root/.pi/agent/sessions \ PI_SKIP_VERSION_CHECK1 \ PI_TELEMETRY0 \ NPM_CONFIG_UPDATE_NOTIFIERfalse RUN mkdir -p /workspace ${PI_CODING_AGENT_SESSION_DIR} \ printf %s\n \ { \ quietStartup: true, \ enableInstallTelemetry: false \ } \ ${PI_CODING_AGENT_DIR}/settings.json WORKDIR /workspace EXPOSE 49983实现上有几个值得注意的细节分层缓存Pi 的 npm 安装单独放一个RUNDockerfile 注释也明确说明这样升版本时只重建这一层避免每次都要重装系统包与 Node.js环境与状态目录预置PI_CODING_AGENT_DIR/root/.pi/agent、PI_SKIP_VERSION_CHECK1、PI_TELEMETRY0让 Pi 无打扰运行状态目录在构建期创建但不写入任何凭证避免跨租户泄露会话基础镜像继承cubesandbox-base自带的 cube-entrypoint 会让 envd 常驻在:49983Cube 因此可以使用标准就绪探针这也是排错表中就绪探针超时 → 确认基础镜像包含 envd的根源。构建并推送docker build --platform linux/amd64 \ -t your-registry/pi-agent-cube:latest \ examples/pi-agent-integration docker push your-registry/pi-agent-cube:latest2. 注册为 Cube 模板cubemastercli tpl create-from-image \ --image your-registry/pi-agent-cube:latest \ --writable-layer-size 4G \ --expose-port 49983 \ --probe 49983 \ --probe-path /health cubemastercli tpl watch --job-id job_id任务变为READY后记下template_id后续每次Sandbox.create()都要用它。4G可写层适合中等任务若 Agent 会安装大型工具链提升到8G。需要了解镜像与模板的底层机制时可参考 Bring Your Own Image 指南 与 从镜像构建模板。3. 配置宿主端驱动cd examples/pi-agent-integration cp .env.example .env # 填写 E2B_API_URL、CUBE_TEMPLATE_ID 以及你的 provider key pip install -r requirements.txt完整的变量模板见examples/pi-agent-integration/.env.example变量作用位置说明E2B_API_URL本地进程CubeAPI 地址http://node:3000注意应使用 CubeAPI 而非 CubeProxyE2B_API_KEY本地进程本地开发填任意非空字符串如e2b_000000启用鉴权后填真实 keyCUBE_TEMPLATE_IDSandbox.create(template...)来自第 2 步CUBE_WARMUP_TEMPLATE_IDrun_pi_warmup.pywarmup 模板任务的 template_idPI_PROVIDER/PI_MODELPi CLI 参数选择 provider 与模型.env.example默认deepseek/deepseek-v4-proANTHROPIC_API_KEYenvs...直连或 CubeEgress 注入vaultprovider 密钥ANTHROPIC_BASE_URL传入 exec 环境Anthropic 兼容网关如 DeepSeek 的https://api.deepseek.com/anthropicPI_LLM_HOSTnetwork_policy.py默认拒绝出网下放行的 LLM hostANTHROPIC_AUTH_TOKEN/ANTHROPIC_MODELPi CLI走 Anthropic 兼容端点时使用从源码看provider 与 key 的对应关系集中维护在examples/pi-agent-integration/env_utils.pyPROVIDER_KEY_ENV定义了 5 个内置 provider 的密钥环境变量名anthropic→ANTHROPIC_API_KEY、openai→OPENAI_API_KEY、google→GEMINI_API_KEY、deepseek→DEEPSEEK_API_KEY、openrouter→OPENROUTER_API_KEY未知 provider 回退为{PROVIDER}_API_KEYPROVIDER_DEFAULT_HOST给出各 provider 的默认 API hostapi.anthropic.com、api.openai.com、generativelanguage.googleapis.com、api.deepseek.com、openrouter.aiPROVIDER_DEFAULT_MODEL仅为anthropicclaude-sonnet-4-6与deepseekdeepseek-v4-pro提供默认模型其他 provider 必须显式设置PI_MODEL否则脚本会以明确报错退出模型 ID 与 provider 强相关没有安全的跨 provider 默认值pi_provider()会做大小写归一化.strip().lower()所以Anthropic与anthropic行为一致。4. 运行时配置与 API Key 注入Pi 命令以无交互方式构造--print表示处理完 prompt 即退出不启动 TUI否则会在 E2B exec 通道上挂死配合显式 provider/model 与--mode json输出机器可读的 JSONL 事件流--approve是布尔开关表示本次运行信任沙箱内的项目本地文件prompt 作为末尾的位置参数传入。命令的完整拼装逻辑在env_utils.py的pi_command()pi --print [--mode json] [--provider P] [--model M] [--thinking T] [--name N] [--approve] prompt。其中--approve可通过approveFalse关闭——在沙箱隔离场景默认开启很方便但若AGENTS.md/CLAUDE.md这类项目本地文件可能在多轮之间被篡改高风险工作流应关闭。两种密钥流转方式共用同一个模板直连方式—— 逐命令传入密钥。e2b的commands.run(envs...)把环境放进 exec 信封而非 VM 内的持久文件因此密钥只在该命令执行期间存在result sandbox.commands.run( cd /workspace pi --print --mode json --provider anthropic --model claude-sonnet-4-6 --approve do something, envs{ANTHROPIC_API_KEY: key}, userroot, timeout900, )保险柜方式—— 让密钥完全不进入 VM见第 6 步。run_pi_agent.py是直连方式的可运行示例examples/pi-agent-integration/run_pi_agent.py它提供了一组 CLI 参数与同名环境变量对应--templateCUBE_TEMPLATE_ID、--prompt、--workspacePI_WORKSPACE默认/workspace、--name默认cube-pi-agent-demo、--sandbox-timeoutPI_SANDBOX_TIMEOUT默认 1800s、--exec-timeoutPI_AGENT_EXEC_TIMEOUT默认 900s、--no-seed跳过写入 demo 项目、--raw输出原始 JSONL 而非精简转写。脚本默认会往沙箱里 seed 一个含README.md与app.py的小项目让 Agent 有一个确定性的任务可跑。驱动脚本对 Pi 输出的处理值得一提_pi_common.pyPi 的--mode json会持续输出大量信封token 级增量、思考轨迹、重复的消息快照jsonl_render_writer()按换行缓冲切分事件流只渲染权威的agent_end转写——助手文本、工具调用含参数摘要、失败项PI_STREAM_RAW1或--raw则直接透传原始 JSONL。run_command()默认以userroot执行因为/workspace与/root/.pi/agent都是 root 属主默认 exec 用户无法写入它还兼容了老版本 SDK 的env参数名仅当明确是envs→env签名不匹配时才重试。5. 会话持久化pause / resumepython resume_pi_agent.py它在 SDK 层复用了快照 / 克隆 / 回滚引擎sandbox.pause()对运行中的 VM内存 rootfs打快照并释放算力。Sandbox.connect(sandbox_id)恢复时/workspace、Pi 状态目录/root/.pi/agent及其他文件都完好无损。生命周期注意用try/finally手动管理沙箱不要用with Sandbox.create(...)context manager。 context manager 在__exit__时会 kill 沙箱这会让 pause 失效。示例显式创建沙箱只在finally里调用sandbox.kill()。sandbox Sandbox.create(templatetemplate_id, timeout1800) try: run_turn(sandbox, prompt_1) # 写入 /workspace/plan.md sandbox_id sandbox.pause() or sandbox.sandbox_id sandbox Sandbox.connect(sandbox_id) assert_state_survived(sandbox) # /workspace /root/.pi/agent 仍在 run_turn(sandbox, prompt_2) # 继续工作 finally: sandbox.kill()resume_pi_agent.py把这一流程落成了两轮对话第一轮让 Pi 只写{workspace}/plan.md随后 pauseassert_state_survived()恢复后先校验plan.md存在且/root/.pi/agent状态目录完好再进入第二轮让 Pi 读取 plan 并实现步骤一。源码中对 pause 返回值做了兼容处理resume_pi_agent.py不同 SDK 版本可能返回恢复句柄字符串或布尔成功标志只有拿到非空字符串才替换 sandbox_id否则沿用原 ID 执行connect()。两次调用复用同一个--name默认cube-pi-agent-resume以保持会话上下文连续。6. 网络与出网策略密钥保险柜network_policy.py展示了推荐用于共享集群的模式默认拒绝出网 链路上注入密钥。规则构造逻辑在build_rules()network_policy.py凭证注入使用原生 cubesandbox SDK详见 安全代理密钥保险柜 出网管控。from cubesandbox import Sandbox, Rule, Match, Action, Inject host api.anthropic.com rules [ Rule( nameallow_anthropic_llm, matchMatch(schemehttps, snihost, hosthost), actionAction(allowTrue, auditmetadata, inject[ Inject(headerx-api-key, secretANTHROPIC_API_KEY, format${SECRET}), Inject(headeranthropic-version, secret2023-06-01, format${SECRET}), ]), ), ] sandbox Sandbox.create( templateCUBE_TEMPLATE_ID, allow_internet_accessFalse, # 默认拒绝规则里的 host 会被自动放行 network{rules: rules}, )注入头的差异同样由env_utils.py的provider_inject()统一生成Anthropic 使用x-api-key 必需的anthropic-version: 2023-06-01两个头其余 provider 使用Authorization: Bearer ${SECRET}。build_pi_env(include_secretsFalse)env_utils.py在保险柜模式下只透传PI_CODING_AGENT_DIR、PI_SKIP_VERSION_CHECK、PI_TELEMETRY及白名单PASSTHROUGH_ENV_NAMESANTHROPIC_BASE_URL、ANTHROPIC_MODEL、PI_CACHE_RETENTION、HTTP_PROXY、HTTPS_PROXY、NO_PROXY绝不携带任何 provider 密钥直连模式也只会转发当前激活 provider 的密钥避免一台有多个 provider key 的宿主把所有密钥泄进沙箱。PI_LLM_HOST的解析优先级在pi_llm_host()显式PI_LLM_HOST 从ANTHROPIC_BASE_URL解析出的 host用于 Anthropic 兼容端点 provider 默认 host。network_policy.py也可用--host覆盖。效果沙箱内printenv ANTHROPIC_API_KEY只显示占位值PLACEHOLDER_KEY cube-egress-managed-placeholder脚本通过show_key_not_in_vm()演示验证。每次访问 LLM host 都会在链路上被附加鉴权头。其他任何目的地都会被 CubeVS 在 L3/L4 层丢弃allow_internet_accessFalse根本无法离开沙箱network_policy.py的show_non_llm_blocked()会实测curl https://example.com得到 403/blocked。每条 allow / deny 决策都会记入出网审计日志。从 安全代理文档 可以进一步理解底层链路CubeEgress 是 host-network 容器通过 TPROXY 监听 8080/8443HTTPS 流量按 SNI 现场签发 leaf 证书签名链根是 CubeEgress 的 root CA构建模板时已烘进沙箱系统 CAaccess_by_lua阶段匹配 L7 规则执行放行/拒绝/注入。规则采用先到先得匹配第一条命中的规则决定结果任何规则都不命中的请求被默认拒绝返回403 Forbidden - CubeEgress。匹配字段scheme/port/sni/host/method/path均为 AND 关系支持*.example.com子域通配与/v1/*前缀匹配详见文档中的匹配字段表。非 Anthropic provider 时示例会改注入Authorization: Bearer头。若某 provider 不接受 header 注入的密钥可回退到直连方式envs...—— 但绝不要把密钥写进沙箱内的持久文件。7. 进阶Pi SDK warmup 预热快照这是原文档配套示例在 README 中补充的进阶方案examples/pi-agent-integration/README_zh.md第 6 节与基于快照的会话持久化主题直接相关。一次性方案每次任务都启动新的pi进程warmup 方案则把常驻 Node adapterpi_warmup_adapter.mjsDockerfile.warmup作为镜像命令启动时创建一个持久化的 Pi SDKAgentSession初始化完成后GET /readyz才返回 HTTP 200。Cube 会等待该探针成功后制作模板快照因此从模板恢复的沙箱中已经包含初始化好的 Node 进程和 sessiondocker build --platform linux/amd64 \ -f Dockerfile.warmup \ --build-arg PI_AGENT_IMAGEyour-registry/pi-agent-cube:latest \ -t your-registry/pi-agent-warmup-cube:latest . docker push your-registry/pi-agent-warmup-cube:latest cubemastercli tpl create-from-image \ --image your-registry/pi-agent-warmup-cube:latest \ --alias pi-warmup \ --writable-layer-size 4G \ --expose-port 49983 \ --expose-port 8080 \ --probe 8080 \ --probe-path /readyz将任务生成的模板 ID 写入CUBE_WARMUP_TEMPLATE_ID用run_pi_warmup.py向恢复出的 session 发送任务adapter 默认端口 8080可用PI_WARMUP_PORT修改python run_pi_warmup.py \ --prompt 创建 hello.py打印 Hello from pre-warmed Pi 并运行它。驱动脚本通过/prompt请求传递 provider keyadapter 只把它放在 Pi 的内存鉴权存储中不会写入 session 或模板快照。单个 adapter 只维护一个 session因此任务串行执行并发请求会收到 HTTP 409。该方案与 prewarm 模板服务 的思路一致即把初始化成本摊进模板快照。使用场景与最佳实践隔离开发。把编码 Agent 跑在沙箱内其文件编辑与 shell 命令无法触及宿主。执行 Agent 生成的代码并回收结果。让 Agent 写入/workspace再通过sandbox.files或commands.run读回产物run_pi_agent.py的show_workspace_result()就演示了执行后lscat result.md的回读流程。长任务断点续跑。用pause()connect()给长时间重构打快照并稍后恢复或从一个快照分叉多个任务变体。把重依赖预装进模板而不是运行时拉取尤其在默认拒绝出网的策略下需要npm install或拉取 MCP 工具的任务要么放行对应 host要么预装进模板。关键代码片段无交互调用 Picmd ( cd /workspace pi --print --mode json --provider anthropic --model claude-sonnet-4-6 --approve Inspect the project, run app.py, and summarize the result. ) result sandbox.commands.run(cmd, envspi_env, userroot, timeout900)preflight 版本检查version sandbox.commands.run(pi --version, timeout60)注意事项Node.js 版本。Pi 需要较新的 Node 运行时基础镜像自带的 apt Node 偏旧务必通过 NodeSource 安装Dockerfile 已如此。Agent 状态目录。/root/.pi/agent保存 Pi 的会话缓存。镜像里保持它为空避免跨租户泄露会话它在构建时创建但不写入任何凭证。直连方式的密钥留存。直连方式envs下密钥仅作用于该 exec 调用但 Pi 可能把 provider 凭证缓存到其状态目录/root/.pi/agent/会在pause()/resume()后仍留在盘上。对隔离要求高时优先用保险柜方式network_policy.py密钥完全不进入 VM。源码注释中对此有明确警示pause 快照同样会捕获 VM 内的 env 与 Pi 缓存的任何凭据扩大了暴露面。CubeEgress CANode。保险柜方式要求沙箱信任 CubeEgress 根 CA基础镜像已把它装入系统 CA 包。但 Pi 基于 Node.js、忽略系统 CA 库因此network_policy.py还会设置NODE_EXTRA_CA_CERTS指向/etc/ssl/certs/ca-certificates.crt可用PI_NODE_EXTRA_CA_CERTS覆盖——否则 vault 路径会以Connection error失败。出网副作用。需要npm install或拉取 MCP 工具的任务要放行相应 host 或预装进模板。交互式 TTY 功能。Pi TUI 在 E2B 协议下不可用。请用无交互--print --mode json多轮对话由宿主脚本驱动。排错现象可能原因处理preflight 报pi: command not foundCLI 变更后未重建模板重建镜像并重新注册模板provider 鉴权失败密钥未传入直连或缺少 inject 规则vault传envs{...}或修正规则的sni/host403 Forbidden - CubeEgress默认拒绝且无匹配放行规则把 LLM host及所需其他 host加入规则vault 下 Pi 报Connection error/ TLS 失败Pi 的 Node 运行时忽略系统 CA 库不信任 CubeEgress CA示例已设NODE_EXTRA_CA_CERTS若 CA 在别处用PI_NODE_EXTRA_CA_CERTS覆盖模板创建卡在PULLINGCube 节点无法访问 registry推送到集群可访问的 registry必要时提供鉴权就绪探针超时基础镜像缺少 envd确认FROM ghcr.io/tencentcloud/cubesandbox-base:2026.16pause()/connect()报错平台版本过低不支持快照升级 CubeSandbox 平台warmup/readyz一直不成功PI_PROVIDER/PI_MODEL不是当前固定 Pi 版本内置的模型查看 adapter 日志改用支持的 provider/model 组合warmup 任务返回 HTTP 409常驻 session 正在处理其他任务等当前任务完成一个 adapter 只维护一个 session参考可运行示例examples/pi-agent-integration含run_pi_agent.py、resume_pi_agent.py、network_policy.py、run_pi_warmup.py、env_utils.py、_pi_common.py、.env.example自定义模板镜像docs/zh/guide/tutorials/bring-your-own-image.md从镜像构建模板docs/zh/guide/tutorials/template-from-image.md快照 / 克隆 / 回滚docs/zh/guide/snapshot-rollback-clone.md密钥保险柜 出网管控docs/zh/guide/security-proxy.mdwarmup 模板服务docs/zh/guide/tutorials/prewarm-template-service.mdPi coding agenthttps://www.npmjs.com/package/earendil-works/pi-coding-agent【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考