Ralph E2B 云沙箱执行指南：在云端隔离环境运行 Claude Code 自主循环

Ralph E2B 云沙箱执行指南在云端隔离环境运行 Claude Code 自主循环【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code本篇技术指南围绕 Ralph 项目Autonomous AI development loop for Claude Code的 E2B 云沙箱能力展开讲解如何通过ralph --sandbox e2b把 Claude Code CLI 的执行从本机迁移到 E2B 云端沙箱从而卸载计算负载、获得一致的临时环境、并让自主执行完全脱离宿主机。读完本文你将掌握 E2B 沙箱的整体架构、完整 CLI 与.ralphrc配置、凭据注入方式、文件双向同步机制、成本估算与预算控制以及从启动到清理的完整生命周期与故障排查方法。一、设计动机为什么把执行搬到 E2B 云端Ralph 的 Docker 沙箱见 docs/DOCKER_SANDBOX.md解决的是本机容器隔离而 E2B 沙箱解决的是另一类需求执行环境完全不在你的机器上。使用 E2B 云沙箱的典型场景包括卸载计算负载Claude 每轮迭代的 CLI 运行在云端宿主机只负责编排一致的临时环境每个 run 对应一个按秒计费的云沙箱环境干净、可复制、用完即销毁保持自主执行脱离宿主机即便宿主机被干扰或需要严格控制网络/文件影响面Claude 的工作目录、进程和产物都在云端。从实现里程碑看E2B 沙箱对应 Issue #75是沙箱 epic #49Phase 6.0的第二个切片首个切片是 Issue #74 的 Docker 沙箱。daytona与cloudflare两个 provider 明确不在计划内Issue #79、#80传入会被拒绝并给出清晰错误。二、整体架构编排留在主机执行搬上云端E2B 沙箱遵循与 Docker 沙箱一致的模型——Ralph 的编排循环控制、限流、熔断、响应分析、退出检测、status.json全部留在宿主机只有 Claude 的执行移动位置。区别在于 E2B 没有 bind mount因此项目文件需要在启动时上传一次、每轮迭代后下载变更文件回宿主机HOST E2B CLOUD SANDBOX (one per run) ralph_loop.sh ── lib/e2b_helper.py exec ───▶ claude -p ... (per iteration) ├─ rate limiting / circuit breaker │ runs in /home/user/workspace ├─ response analysis / exit detection ▼ ├─ status.json (ralph-monitor) project copy ◀── upload at start ├─ cost tracking / --sandbox-max-cost changed files ── download after every loop ──▶ host └─ sandbox kill on exit / CtrlC架构上有四个关键设计决策均可在源码中找到依据SDK 语言壁垒由 Python 薄封装打通。E2B 官方 SDK 只有 Python/JS 两种语言而 Ralph 的主循环是 bash因此所有 API 流量都经过 lib/e2b_helper.py一个对官方e2bPython 包的薄 CLI 封装。exec子命令会流式转发远端命令的 stdout/stderr 并原样传播远端退出码见 lib/e2b_helper.py所以--livestream-json与后台模式都无需改动即可工作。一次 run 一个沙箱跨迭代复用。E2B 按秒计费若每轮迭代都新建沙箱成本会成倍增长还会丢失 Claude 在沙箱内的会话状态会话连续性失效。因此沙箱在启动时创建一次、被所有迭代复用--sandbox-keep-alive可让它在退出后继续存活供后续通过--sandbox-id复用。文件同步替代 bind mount。项目被跟踪与未被忽略的未跟踪文件外加.ralph控制文件在启动时上传一次沙箱内被修改的文件在每一轮迭代结束后下载回宿主机。这样进度检测、熔断器、ralph-monitor全部照常工作在宿主机侧。删除与重命名也会回传每次下载的归档中都携带一份沙箱当前文件的清单manifest宿主机中之前已同步、但已从清单消失的文件会被删除宿主机独有文件、.git、.ralph永远不会成为删除候选。同步内容可用--sync-include/--sync-exclude标志、项目根目录的.ralphignore文件和大文件策略过滤详见 docs/SANDBOX_SYNC.md。绝不静默降级。如果沙箱初始化失败缺少 SDK、API key 无效、API 不可达Ralph 直接报错退出而不会在用户要求保护的主机上悄悄运行 Claude——init_e2b_sandbox与start_e2b_sandbox的任一失败都会中止整个 run见 ralph_loop.sh。三、快速开始最小可用配置前置条件宿主机已安装 Ralph且 Python 环境可用helper 默认使用python3。三步即可启用 E2B 沙箱pip install e2b # 官方 E2B Python SDK export E2B_API_KEYe2b_... # 从 E2B 控制台获取 # —— 或者把密钥落盘存储 mkdir -p ~/.ralph ( umask 177 echo e2b_... ~/.ralph/e2b_api_key ) ralph --sandbox e2b沙箱内必须有 Claude CLI。Ralph 使用的默认base模板在首次运行时会自动引导安装npm install -g anthropic-ai/claude-code若希望启动更快可以构建一个预装好 Claude CLI 的自定义 E2B 模板并用--sandbox-template传入。从源码看lib/sandbox_e2b.sh 中的_ensure_claude_in_e2b会先探测claude --version失败后再尝试npm install -g anthropic-ai/claude-code二次探测仍失败时会把 npm 输出的最后几行作为诊断信息记录用于区分仓库不可达与模板缺 npm最终报错并提示构建自定义模板。第一次在普通模板上运行需要为这次 npm 引导付出计费成本使用自定义模板可完全规避。四、CLI 参考E2B 子标志与校验规则E2B 沙箱的全部开关都是--sandbox e2b的子标志完整清单如下Flag默认值说明--sandbox e2b关闭启用 E2B 云沙箱执行--sandbox-template TbaseE2B 模板名自定义模板可预装 claude--sandbox-id ID新建沙箱复用既有沙箱与--sandbox-keep-alive搭配--sandbox-timeout SECS3600沙箱会话超时过期沙箱会被自动重建并重新上传--sandbox-keep-alive关闭退出时保留沙箱运行计费继续--sandbox-max-cost USD无估算成本达到该金额时优雅停止循环--sandbox-cost-alert USD无估算成本达到该金额时只警告一次标志归属是硬约束。Docker 子标志--sandbox-image等只配--sandbox dockerE2B 子标志只配--sandbox e2b混用是启动期错误见 ralph_loop.sh。同理--sync-include/--sync-exclude只对 e2b provider 有效——Docker 的 bind mount 实时共享一切无需也不允许过滤混用会报错见 ralph_loop.sh。这些标志在提交给底层时还会经过严格校验validate_e2b_sandbox_config见 lib/sandbox_e2b.sh模板名只允许字母数字加.、_、-且必须以字母数字开头——这一正则同时阻断了 shell 元字符进入远端命令行沙箱 ID 只允许字母数字加_、---sandbox-timeout必须是正整数0也会被拒绝--sandbox-max-cost、--sandbox-cost-alert、SANDBOX_E2B_COST_PER_HOUR必须是合法的十进制数如5.00。单元测试 tests/unit/test_sandbox_e2b.bats 对这些拒绝路径逐一有断言包括恶意模板名evil;rm -rf /、非数字超时soon、零超时与非数字金额等。五、.ralphrc 配置与优先级规则与 CLI 标志等价的项目级配置如下CLI 标志优先于.ralphrcAPI key 本身绝不写入.ralphrcSANDBOX_PROVIDERe2b SANDBOX_E2B_TEMPLATEbase SANDBOX_E2B_TIMEOUT3600 SANDBOX_E2B_KEEP_ALIVEfalse SANDBOX_E2B_MAX_COST5.00 SANDBOX_E2B_COST_ALERT2.00 SANDBOX_E2B_COST_PER_HOUR0.10这套变量的默认值同时定义在 lib/sandbox_e2b.sh 中.ralphrc模板templates/ralphrc.template也保留了带注释的副本。三个层面的优先级是 Ralph 全项目统一的规则CLI 标志 环境变量 .ralphrc 默认值。在 ralph_loop.sh 中同名环境变量会在读取.ralphrc之后覆盖其值随后命令行解析ralph_loop.sh再次覆盖。另外--monitortmux 模式会把全部沙箱标志转发到循环窗格——只有非默认值会被转发规则与 Docker provider 完全一致见 ralph_loop.sh。六、凭据管理两套互相独立的密钥E2B 沙箱涉及两套密钥两者都不会出现在命令行上实现上e2b_helper.py从环境读取密钥、通过 stdin 传递文件内容详见 lib/e2b_helper.py1. E2B API keysetup_e2b_credentials见 lib/sandbox_e2b.sh按序解析E2B_API_KEY环境变量~/.ralph/e2b_api_key密钥文件若权限不是chmod 600会记录警告日志密钥值会被剥离空白后读取绝不进入日志。2. 沙箱内 Claude 的认证_seed_e2b_claude_credentials与 Docker provider 的凭据处理互相镜像见 lib/sandbox_e2b.sh按序处理宿主机设置了ANTHROPIC_API_KEY——在创建沙箱时作为环境变量注入helper 从自身环境读取见 lib/e2b_helper.py宿主机存在~/.claude/.credentials.json——通过 stdin复制进沙箱 home远端chmod 600路径/home/user/.claude/.credentials.json。宿主机原文件永不被修改两者皆无——记录警告并继续循环适用于认证已内置在自定义模板中的场景。单测对凭据解析覆盖得很细tests/unit/test_sandbox_e2b.bats环境变量优先于密钥文件、644 权限会触发 chmod 600 提示、无密钥时报错信息同时包含E2B_API_KEY与e2b_api_key两个线索。沙箱创建时若检测到ANTHROPIC_API_KEYmock 还会额外记录看到环境变量的痕迹并断言密钥值从未以 argv 形式出现tests/unit/test_sandbox_e2b.bats。七、文件同步上传一次、每轮回传、删除随清单传播E2B 沙箱没有 bind mount文件传输完全由同步层承担其过滤逻辑在 lib/sync.sh 中实现、由 lib/sandbox_e2b.sh 驱动。完整规则见 docs/SANDBOX_SYNC.md这里给出与 E2B 执行直接相关的要点。上传方向upload_project_to_e2blib/sandbox_e2b.sh上传清单由git ls-files -coz --exclude-standard构建被跟踪 未被忽略的未跟踪文件天然尊重.gitignore再依次经过SYNC_INCLUDE/--sync-include——若设置仅匹配的文件上传SYNC_EXCLUDE/--sync-exclude——匹配的文件被剔除.ralphignore——项目根目录的额外排除模式大文件策略——超过SYNC_MAX_FILE_SIZE默认 10MB的文件默认警告保留SYNC_LARGE_FILE_ACTIONwarn或直接丢弃skip。其中.ralph控制文件.ralphrc、PROMPT.md、fix_plan.md、AGENT.md、specs/永远上传绕过一切过滤——循环绝不能让自己饿死丢掉自己的提示词与计划。反之.ralph内部状态.e2b_sandbox_state、status.json、日志等被整体排除防止沙箱侧写入回传覆盖宿主机控制状态。下载方向sync_e2b_artifacts_downlib/sandbox_e2b.sh只下载上次同步后变更的文件过滤规则仅含SYNC_EXCLUDE.ralphignore。有两个刻意的不对称include 模式不作用于下载——Claude 在 include 集合之外创建的产物构建输出、报告依然回传想过滤用 exclude 模式大文件策略仅限上传——沙箱侧文件在传输前无法测量大小。删除与重命名传播download子命令生成的归档里含一个.ralph_e2b_manifest成员记录沙箱当前全部文件见 lib/e2b_helper.py宿主机以.ralph/.e2b_synced_files为删除基线删除同步基线用comm求出基线有、清单无的候选集后再删除lib/sandbox_e2b.sh。安全护栏包括.git、.ralph、绝对路径、含..的路径即使基线被污染也绝不删除匹配排除模式的主机文件永不是删除候选被下载过滤掉的文件不进入删除基线避免同名主机文件因沙箱删除副本而遭殃。ack 机制保证至少一次投递同步标记sync marker位于工作区之外/home/下不会被误打包进上传/下载内容且只在宿主机成功解包并完成删除扫描后才由ack-download推进见 lib/e2b_helper.py。若 ack 丢失下一轮迭代会重新投递同样的变更——重新解包是幂等覆盖。测试断言了download 成功才 ack、失败绝不 acktests/unit/test_sandbox_e2b.bats以及.git内容永远不被解包tests/unit/test_sandbox_e2b.bats。同步过程会输出人类可读的进度摘要任何丢弃都不会静默发生Uploading 412 file(s) (2.3MB compressed) to E2B sandbox... Uploaded 412 file(s) to E2B workspace /home/user/workspace Synced 7 changed file(s) (18.2KB) from the E2B sandbox Filtered 3 file(s) from sandbox download (SYNC_EXCLUDE / .ralphignore patterns) Large file in sync: data/fixtures.bin (24.0MB 10.0MB limit; SYNC_LARGE_FILE_ACTIONskip to drop)八、成本跟踪按秒估算、跨重建累计、预算硬停E2B 按沙箱运行秒数计费。Ralph 把估算花费计算为所有沙箱时段之和当前激活时段 会话过期后重建的既往时段×SANDBOX_E2B_COST_PER_HOUR默认$0.10/h请根据模板规格对照 E2B 定价页调整。这个费率仅用于成本估算与限额执行。关键实现细节update_e2b_cost与check_e2b_cost_limits见 lib/sandbox_e2b.sh被替换沙箱的已产生成本会在纪元epoch重置前折叠进accrued_cost状态文件.ralph/.e2b_sandbox_state中的字段所以--sandbox-max-cost覆盖的是整个 run 的累计花费而不是当前沙箱时段——一个反复过期/重建的 run 不会从零重新计预算。单测专门验证了这一跨重建累计tests/unit/test_sandbox_e2b.bats。实时估算值出现在status.json的sandbox.estimated_cost字段与ralph-monitor的 Sandbox 面板中get_e2b_sandbox_status输出provider、sandbox_id、status、estimated_cost。--sandbox-cost-alert到达阈值时只记录一次警告状态文件中的cost_alerted字段防止重复提醒。--sandbox-max-cost到达时优雅停止循环先做最终产物同步再杀沙箱退出原因为e2b_cost_limit见 ralph_loop.sh。每次 run 结束都会向.ralph/logs/e2b_cost.log追加一行汇总时间戳、沙箱 ID、运行秒数、估算成本。需要强调的是这是预算控制用的估算值不是账单——实际用量请以 E2B 控制台为准。九、生命周期与故障处理E2B 沙箱的完整生命周期由 lib/sandbox_e2b.sh 中的函数编排启动init_e2b_sandbox配置校验 → SDK 可用性 → API key 解析并写入初始状态文件见 lib/sandbox_e2b.sh→start_e2b_sandbox创建沙箱或--sandbox-id连接、凭据注入、项目上传、claude 引导检查。任一失败都中止 run。每轮迭代构建好的 Claude 命令数组被包装为python3 lib/e2b_helper.py exec --sandbox-id id --cwd /home/user/workspace -- claude ...build_e2b_exec_argslib/sandbox_e2b.sh每次迭代后无论成功、失败还是超时都会先下载变更文件并执行删除扫描再进入进度检测。注意 SDK 侧timeout0表示禁用 SDK 内建限制迭代预算完全由宿主机侧的portable_timeout掌控退出码 124。会话过期E2B 会在会话超时后杀掉沙箱。每轮迭代执行前的存活探测ensure_e2b_sandbox调用info子命令会发现这一情况并自动启动替代沙箱全新创建 重新上传。值得注意的降级策略get_info失败不会误判存活的沙箱为死亡避免每轮都重建一个活得好好的沙箱见 lib/e2b_helper.py。超时exit 124宿主机侧超时只杀掉本地 helper 客户端沙箱内残留的claude进程会在下一轮迭代前被远端pkill清理handle_e2b_sandbox_timeoutlib/sandbox_e2b.sh。退出先做最终产物同步再杀掉沙箱计费停止——覆盖优雅完成、熔断停机、成本上限、错误与 SIGINT/SIGTERM 所有路径。若开了--sandbox-keep-alive则保留沙箱并记录其 ID 供复用。清理是幂等的重复调用不会重复 kill见 tests/unit/test_sandbox_e2b.bats。状态.ralph/.e2b_sandbox_stateJSON通过 temp 文件 mv原子写入记录模板、沙箱 ID、状态、estimated_cost、accrued_cost重建时并入既往时段成本等.ralph/.e2b_synced_files是删除同步基线沙箱中已知存在的项目路径集合。十、已知限制沙箱内的 git 提交不会同步回来。同步基于文件内容.git在双向都被排除沙箱侧 git 状态绝不能覆盖宿主机仓库。Claude 的变更以宿主工作区的未提交修改形式到达请在宿主机侧提交或交给下一个宿主机侧工具处理。网络限制不可配置。E2B 沙箱默认具备出网能力Claude API 本来也需要出网安全策略属于 Issue #78 的范畴。首次引导成本普通模板首次运行要支付npm install -g引导成本用自定义模板可规避。十一、故障排查症状修复E2B SDK unavailable ... pip install e2bpip install e2b安装到 Ralph 使用的 python3 环境E2B API key not foundexport E2B_API_KEY...或创建~/.ralph/e2b_api_keychmod 600Claude Code CLI is unavailable in the E2B sandbox构建预装anthropic-ai/claude-code的自定义 E2B 模板并传入--sandbox-template沙箱内 Claude 认证错误导出ANTHROPIC_API_KEY或先在宿主机登录使~/.claude/.credentials.json存在循环以e2b_cost_limit停止符合预期——调高--sandbox-max-cost或按模板实际费率修正SANDBOX_E2B_COST_PER_HOUR硬杀kill -9后残留沙箱它会在--sandbox-timeout时自动过期也可从 E2B 控制台提前终止十二、与 Docker 沙箱的选择若你的场景需要本机容器隔离与实时文件共享bind mount、零同步开销、会话状态随容器存活选择--sandbox docker详见 docs/DOCKER_SANDBOX.md若需要完全脱离宿主机、按秒计费、用完即销毁的云端临时环境选择--sandbox e2b。两者共享同一套编排留宿主机、执行进沙箱、失败不静默降级的架构理念区别只在于文件传输模型Docker 实时 bind mount vs E2B 快照上传 每轮迭代回传与成本模型Docker 常驻容器 vs E2B 按秒计费 可配预算硬停。选择 E2B 时建议结合 docs/SANDBOX_SYNC.md 的过滤规则规划项目文件并用--sandbox-max-cost守住预算底线。【免费下载链接】ralph-claude-codeAutonomous AI development loop for Claude Code with intelligent exit detection项目地址: https://gitcode.com/GitHub_Trending/ra/ralph-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考