尧图网站建设 
cube-sandbox 与 SWE-bench 评测基于 E2B 兼容沙箱构建 LLM Agent 编程评测与 RL 训练基础设施【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox本文对应仓库 examples/mini-rl-training 示例的完整需求文档PRD.mdv1.0并辅以该示例的源码补丁、配置与脚本作为实现级佐证。文中涉及的完整实操步骤可进一步参考 README_zh.md 与 scripts/README.md。导读本文讲解如何在 cube-sandbox 轻量级虚拟化平台上以SWE-bench软件工程基准测试为应用场景将 LLM Agentmini-swe-agent接入 E2B 兼容沙箱环境自动化解决真实 GitHub issue 并进行测试通过率评测。读完本文你将掌握cube-sandbox 与 E2B SDK 的兼容接入原理、mini-swe-agent 的 E2B 环境改造细节、从镜像注入 envd 到模板注册再到评测运行的完整操作链以及为后续 RL强化学习训练建立批采样、奖励计算与轨迹收集基础设施的设计思路。1. 项目背景cube-sandbox 与 E2B 兼容体系cube-sandbox是一个轻量级虚拟化平台其管理流和数据流完全兼容 E2B SDK。平台通过沙箱内的 agentenvd提供 gRPC 接口支持命令执行、文件读写和沙箱生命周期管理。这意味着任何基于 E2B SDK 编写的应用都可以无差别地运行在 cube-sandbox 之上。本示例以 SWE-bench 为落点演示了四个层层递进的能力使用 cube-sandbox 创建隔离的代码执行环境通过 E2B SDK 驱动 LLM Agent 在沙箱内交互式解题自动化评测 Agent 的解题能力为后续 RL强化学习训练建立基础设施。2. 目标从单题评测到 RL 训练闭环2.1 短期目标本 Example提供一个可运行的端到端示例覆盖从镜像准备到评测完成的全部环节支持多 LLM 模型切换Gemini、GLM、MiniMax、Kimi 等输出结构化的评测结果patch、步骤数、费用、耗时。2.2 长期愿景RL 训练循环PRD 将评测流水线进一步抽象为完整的 RL 训练循环┌─────────────────────────────────────────────────────────────────┐ │ RL Training Loop │ │ │ │ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Policy │ │ Action │ │ Env │ │ Reward │ │ │ │ (LLM) │───►│ bash 命令 │───►│ E2B 沙箱 │───►│ 测试通过率│ │ │ │ │◄───│ │◄───│ testbed │◄───│ │ │ │ └──────────┘ └───────────┘ └──────────┘ └──────────┘ │ │ ▲ │ │ │ └────────────── Policy Update ◄──────────────────┘ │ └─────────────────────────────────────────────────────────────────┘该循环与 RL 概念的一一对应关系正是本示例被设计为RL 训练基础设施的根本原因RL 概念对应实现Environmentcube-sandbox 沙箱通过 E2B SDK 管理Statetestbed 中的代码仓库状态 命令历史ActionAgent 生成的 bash 命令RewardSWE-bench 测试通过率0 或 1PolicyLLM可通过 RL 微调优化3. 系统架构3.1 整体拓扑┌─────────────────┐ ┌──────────── cube-sandbox ────────────┐ │ │ │ │ │ mini-swe-agent │ E2B SDK │ ┌──────────────┐ │ │ (LLM Agent) │─────────►│ │ envd │──► bash 命令执行 │ │ │ HTTPS/ │ │ :49983 │──► 文件读写 │ │ ┌───────────┐ │ gRPC │ └──────────────┘ │ │ │ LiteLLM │ │ │ │ │ │ ┌──────┐ │ │ │ ┌──────────────────────────────┐ │ │ │ │Gemini│ │ │ │ │ /testbed │ │ │ │ │GLM-5 │ │ │ │ │ (SWE-bench repo testcase) │ │ │ │ │Kimi │ │ │ │ └──────────────────────────────┘ │ │ │ │... │ │ │ │ │ │ │ └──────┘ │ │ └───────────────────────────────────────┘ │ └───────────┘ │ └─────────────────┘3.2 关键组件组件说明mini-swe-agent开源 LLM Agent 框架支持多轮 tool call 交互LiteLLM统一 LLM API 接口支持 OpenAI、Gemini、TokenHub 等E2B SDKPython 客户端通过Sandbox类管理沙箱生命周期envdcube-sandbox 的 in-sandbox agent静态链接二进制监听:49983SWE-bench软件工程基准测试集包含真实 GitHub issue 测试用例3.3 E2B SDK 接口示例中实际用到的 E2B SDK 接口可归纳为五类操作接口功能Sandbox(template...)从模板创建沙箱sbx.commands.run(cmd, user...)执行 bash 命令sbx.files.read(path)读取文件内容sbx.files.write(path, content)写入文件sbx.files.list(dir)列出目录sbx.kill()销毁沙箱需要说明本示例的评测场景主要使用commands.run执行 shell 命令文件读写接口则面向更通用的 Agent 文件操作场景。在仓库的并发压测模式benchmark中还会用echo ok作为沙箱创建/销毁的验证命令见 scripts/README.md。4. mini-swe-agent 改造为 LLM Agent 接入 E2B 沙箱mini-swe-agent 原生支持 Docker、Singularity 等执行环境但不支持 E2B。为接入 cube-sandbox需要对 mini-swe-agent 做最小化改造。改造后的补丁代码位于 mini-swe-agent-patch。4.1 修改的文件文件改动environments/extra/e2b.py新增— E2B 环境类封装 E2B SDK 的沙箱操作environments/__init__.py注册e2b到环境类型映射表_ENVIRONMENT_MAPPINGrun/benchmarks/swebench.py在get_sb_environment中将e2b加入支持image参数的类型列表安装补丁的方式先安装 mini-swe-agent再运行补丁脚本将文件覆盖到 site-packagespip install mini-swe-agent[extra] bash install.sh4.2 E2BEnvironment 类实现核心实现位于 environments/extra/e2b.py约 130 行 Python。配置类E2BEnvironmentConfig基于 pydanticBaseModelclass E2BEnvironmentConfig(BaseModel): template_id: str # E2B 模板 ID或从 CUBE_TEMPLATE_ID 环境变量读取 image: str # SWE-bench 兼容字段实际不使用 cwd: str /testbed # 工作目录 timeout: int 60 # 单条命令超时秒 user: str root # 执行用户 sandbox_timeout: int 1800 # 沙箱生命周期秒核心方法方法功能__init__通过Sandbox.create(templatetemplate_id)创建 E2B 沙箱execute(action)拼接cd {cwd} {command}通过sbx.commands.run()执行合并 stdout/stderr_check_finished(output)检测输出首行是否为COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT若是则抛出Submitted异常触发提交cleanup()调用sbx.kill()销毁沙箱释放资源命令执行流程Agent 发出 action {command: grep -r def _build_app_dict .} │ ▼ E2BEnvironment.execute() │ 拼接: cd /testbed grep -r def _build_app_dict . ▼ sandbox.commands.run(full_cmd, userroot, timeout60) │ 通过 HTTPS/gRPC 发送到 envd ▼ envd 在沙箱内执行 bash 命令 │ ▼ 返回 {output, returncode, exception_info} │ ▼ _check_finished() 判断是否提交 patch结合源码可以看到几个值得注意的细节提交协议_check_finished要求输出首行恰好为COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT且returncode 0此时将剩余行作为submission随Submitted异常抛出raise Submitted({...})交由 Agent 框架完成 patch 提交。超时自愈execute捕获TimeoutError后先cleanup()销毁沙箱再重新抛出避免超时命令污染后续状态。异常归一化普通命令异常被包装为{output, returncode: -1, exception_info}结构并附带exception_type/exception字段供上层观测模板渲染。4.3 环境注册在environments/__init__.py的_ENVIRONMENT_MAPPING中添加一行_ENVIRONMENT_MAPPING { docker: ..., singularity: ..., # ... e2b: minisweagent.environments.extra.e2b.E2BEnvironment, # 新增 }4.4 SWE-bench 入口适配在run/benchmarks/swebench.py的get_sb_environment()中将e2b加入支持image参数的环境列表if env_config[environment_class] in [docker, swerex_modal, e2b]: env_config[image] image_name这样 SWE-bench 运行器会自动将题目对应的 Docker 镜像名传给 E2B 环境配置E2B 环境类内部忽略image字段使用template_id。4.5 源码级深入并发与性能优化e2b.py 在 PRD 描述的基础实现之上还包含面向大规模并行评测的三处关键设计这是把评测流水线推向 RL 训练基础设施的关键① 共享 HTTP 连接池。默认 E2B SDK 每次创建/销毁沙箱都会新建httpx.Client与 TCP 连接产生重复的 TCP TLS 握手开销。_get_shared_api_client()用单例 锁的方式复用一个连接池Limits(max_connections50, max_keepalive_connections50, keepalive_expiry300)使 keep-alive 连接在多次 API 调用间复用。② 沙箱预创建SandboxInfo。create_sandbox_info()是独立的顶层函数仅负责通过POST /sandboxes创建沙箱并返回连接信息sandbox_id、sandbox_domain、envd_version、envd_access_token、api_call_ms随后E2BEnvironment可通过_connect_existing()直接连上已存在的沙箱跳过创建 API 调用。batch_create_sandboxes()进一步用ProcessPoolExecutor默认 8 worker并行预创建一批沙箱——每个 worker 进程持有独立的连接池规避 GIL 限制实现真正的并行创建。失败条目以None占位不影响整体进度。③ 进程退出兜底清理。模块通过atexit.register与SIGINT/SIGTERM信号处理器注册_cleanup_all_sandboxes()用weakref跟踪所有活跃沙箱保证评测进程异常退出时不残留实例。5. 核心流程5.1 镜像准备SWE-bench 原始镜像 ──► envd 注入 ──► 注册为 cube-sandbox 模板从cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest提取 envd 二进制境外访问请使用cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest将 envd 注入 SWE-bench 镜像Dockerfile 覆盖 ENTRYPOINT将注入后的镜像注册为 cube-sandbox 模板获得template_id。envd 注入的实际 Dockerfile 位于 envd-inject/DockerfileARG BASE_IMAGE FROM ${BASE_IMAGE} COPY envd /usr/bin/envd RUN chmod x /usr/bin/envd ENTRYPOINT [/usr/bin/envd, -isnotfc]可以看到 envd 被放置到/usr/bin/envd并作为容器ENTRYPOINT带-isnotfc参数这正是 PRD 中注入后必须设置为ENTRYPOINT [/usr/bin/envd]约束的落地实现。日常使用无需手工构建仓库已提供预构建的公开镜像已注入 envd可直接从cube-sandbox-image.tencentcloudcr.com/demo/django_1776_django-13447:latest拉取。如需为其他 SWE-bench 题目注入 envd可运行 scripts/inject-envd.shbash scripts/inject-envd.sh swebench/sweb.eval.x86_64.django_1776_django-13447:latest脚本会将源镜像与注入后的新镜像推送到镜像仓库随后即可用cubemastercli创建模板cubemastercli tpl create-from-image \ --image cube-sandbox-image.tencentcloudcr.com/demo/django_1776_django-13447:latest \ --writable-layer-size 1G \ --expose-port 49983 \ --cpu 4000 \ --memory 8192 \ --probe 49983参数说明--image已注入 envd 的 SWE-bench 镜像地址--writable-layer-size可写层大小沙箱内文件修改空间--expose-portenvd gRPC 端口固定 49983--cpuCPU 配额毫核4000 4 核--memory内存配额MB8192 8G--probe健康检查端口与 expose-port 一致命令输出的template_id填入.env的CUBE_TEMPLATE_ID。注意这里同时暴露了--expose-port与--probe均为 envd 监听端口 49983——envd 的连通性检查通过该端口的探活完成。5.2 评测流程加载 SWE-bench 题目 │ ▼ 创建 E2B 沙箱template_id │ ▼ ┌──────────────────────┐ │ Agent 交互循环 │ │ ① LLM 分析问题 │ │ ② 生成 bash 命令 │ │ ③ E2B 执行命令 │ │ ④ 返回结果给 LLM │ │ ⑤ 重复直到提交 patch │ └──────────────────────┘ │ ▼ 提取 patch 评估结果 │ ▼ 销毁沙箱5.3 RL 训练扩展愿景在评测流程基础上增加四件事即可升级为 RL 训练循环Batch 采样并行创建多个沙箱同一题目多次尝试Reward 计算reward 1 if tests_pass else 0可扩展为部分分Trajectory 收集记录 (state, action, reward) 序列Policy Update使用 GRPO/PPO 等算法更新 LLM 权重。PRD 明确了 cube-sandbox 在此场景下的三点优势沙箱创建/销毁开销低秒级适合大规模并行采样E2B SDK 兼容性确保与主流工具链无缝集成envd 无依赖注入支持任意 Linux 镜像。从仓库现状看并发基础设施沙箱预创建、进程池批量创建、共享连接池已经在 run-concurrent.py 与 e2b.py 中落地RL 训练本身GRPO/PPO 实现被明确列为非目标。6. 快速开始从依赖安装到单题评测6.1 前置条件Python 3.10Docker用于构建 envd 注入镜像cube-sandbox 平台访问权限API URL API Key至少一个 LLM API KeyGemini / TokenHub / OpenAI 等6.2 安装依赖与补丁pip install -r requirements.txt bash mini-swe-agent-patch/install.sh也可以使用 scripts/setup-env.sh 一键完成 Python 版本检查、依赖安装、库验证与.env初始化。6.3 配置环境变量cp .env.example .env关键变量对应 README_zh.md 的 Step 3# HuggingFace 镜像国内网络使用 hf-mirror.com 避免超时 HF_ENDPOINThttps://hf-mirror.com # cube-sandbox 平台连接信息 E2B_API_URLhttp://your-cube-sandbox-ip:3000 E2B_API_KEYyour-api-key # SWE-bench 镜像模板 ID CUBE_TEMPLATE_IDyour-template-id # SSL 证书自部署平台需要仅作用于 E2B SDK 连接 CUBE_SSL_CERT_FILE/etc/pki/tls/cert.pem # LLM API Key选择一个或多个 GEMINI_API_KEYyour-gemini-key TOKENHUB_API_KEYyour-tokenhub-key OPENAI_API_KEYyour-openai-key注意template_id的解析顺序是配置 YAML 中environment.template_id优先其次才是环境变量CUBE_TEMPLATE_ID对应 e2b.py 中self.config.template_id or os.environ.get(CUBE_TEMPLATE_ID, )的逻辑。6.4 运行单次评测使用 Gemini 3 Flash 解决django__django-13447bash scripts/run-swebench.sh \ --model gemini/gemini-3-flash-preview \ --instance django__django-13447 \ --config configs/e2b-swebench.yamlrun-swebench.sh 的主要参数参数必填默认值说明--model✅LLM 模型名如deepseek/deepseek-chat--instance✅SWE-bench 实例 ID如django__django-13447--configconfigs/e2b-swebench.yamlYAML 配置文件--subsetlite数据集子集lite/verified/full--splittest数据集分割test/dev--step-limit配置文件中的值最大 Agent 步数覆盖配置文件--outputresults/输出目录运行结果保存在results/model/instance/下包含trajectory.jsonAgent 交互轨迹与run.log运行日志。6.5 基础配置剖析e2b-swebench.yaml 展示了三类核心配置agentsystem/instance 提示词模板、step_limit: 100、cost_limit: 3.0、mode: yoloenvironmentcwd: /testbed、timeout: 60、user: root、environment_class: e2b——注意 SWE-bench 镜像以 root 运行因此必须显式指定user: rootmodelobservation_templateJinja2 模板控制如何把命令输出、returncode、异常信息回传给 LLM超过 10000 字符的输出会被截断为 head/tail 各 5000 字符并提示 elided 字符数、format_error_template、model_kwargs。observation_template与_check_finished共同构成了 Agent 与沙箱之间的观察-提交协议普通输出按 returncode/异常/正文三段回传而首行为提交标记的输出则触发Submitted异常进入 patch 提交路径。7. 多模型切换与并发评测7.1 多模型切换示例通过 LiteLLM 统一模型名并准备了多套配置模型命令示例配置文件Gemini直连--model gemini/gemini-3-pro-previewe2b-swebench.yamlGLM-5 / MiniMax / DeepSeek V3.2TokenHubexport OPENAI_API_KEY$TOKENHUB_API_KEY; --model openai/glm-5e2b-tokenhub.yamlKimi K2.5 / DeepSeek R1 / 混元 ThinkingTokenHub需禁用 thinking--model openai/kimi-k2.5e2b-kimi.yamlDeepSeek Chat直连--model deepseek/deepseek-chate2b-deepseek.yamlDeepSeek Reasoner直连禁用 thinking--model deepseek/deepseek-reasonere2b-deepseek-reasoner.yamlTokenHub 与 DeepSeek 直连配置的区别仅在model_kwargs.api_basehttps://tokenhub.tencentmaas.com/v1与https://api.deepseek.com普通模型配置drop_params: trueparallel_tool_calls: true。7.2 Thinking 模型的特殊处理Kimi K2.5 等 Thinking 模型默认开启思考模式其reasoning_content与 LiteLLM 的 tool call 消息格式不兼容多轮 tool call 会报reasoning_content is missing错误。解决方式是在配置中显式禁用 thinking见 e2b-kimi.yamlmodel: model_kwargs: api_base: https://tokenhub.tencentmaas.com/v1 drop_params: true parallel_tool_calls: true extra_body: thinking: type: disabled7.3 高并发评测与纯沙箱压测run-concurrent.py 提供两种模式benchmark纯沙箱创建/销毁吞吐压测无需 LLM如python scripts/run-concurrent.py benchmark -w 50 -n 100 --keep50 并发创建 100 个沙箱并保留不销毁swebench高并发评测支持--repeat同题多次、--pre-create进程池预创建沙箱任务启动即直连、--template-map实例到模板的 JSON 映射。常用参数参数说明-m模型名逗号分隔多个或tokenhub表示全部 TokenHub 模型--repeat N每个模型重复 N 次--pre-create多进程预创建沙箱任务启动时直连--pre-create-workers N预创建并发数-w N任务执行并发数--step-limit N限制 Agent 最大步数--sandbox-only跳过 LLM纯沙箱压测--max-rows NTUI 显示行数0显示全部多实例映射通过 template-mapping.json 提供未列出的实例回退到.env中的CUBE_TEMPLATE_ID。该工具还内建实时 TUI 仪表盘Header/Stats/Tasks/cubecli ls 面板可观测每个任务的创建耗时分布avg/p50/p95/max与总 Cost运行结束输出创建耗时直方图与失败任务明细——这正是 RL 批量采样所需的观测能力。8. 已验证结果8.1 多模型评测django__django-13447E2B 沙箱环境模型步骤费用耗时结果Kimi K2.542$0.93179 秒成功Gemini 3 Pro22$0.26224 秒成功Gemini 3 Flash46$0.19278 秒成功MiniMax M2.756$1.62363 秒成功GLM-541$0.75400 秒成功上述数据来自 PRD v1.0 的已验证结果章节测试题目为django__django-13447README_zh.md 中另有 DeepSeek Chat35 步 / $0.02 / 253s成功与 DeepSeek Reasoner75 步 / $0.05 / 389s成功的记录其余模型标注待测。这些是仓库内记录的实测数据读者可在自己的平台环境中复现验证。8.2 Docker 直连 vs E2B 沙箱Gemini 3 Flash, django__django-13447指标Docker 直连E2B 沙箱差异耗时208 秒278 秒34%步骤49 步46 步-6%费用$0.16$0.1919%PRD 指出E2B 额外耗时主要来自沙箱创建网络开销和 HTTPS/gRPC 传输延迟整体性能损耗在可接受范围内。从实现层面看这也是 e2b.py 引入共享连接池与沙箱预创建的直接动机——通过复用连接与并行创建可以进一步压缩沙箱创建网络开销这一占比。9. 技术约束与注意事项9.1 SSL 证书自部署 cube-sandbox 使用 mkcert 证书客户端需要安装 cube-sandbox 节点的 root CA 到系统信任链设置SSL_CERT_FILE环境变量指向系统证书包Python httpx/certifi 需要。实操上从 cube-sandbox 节点导出 root CA 并安装# 从 cube-sandbox 节点获取 root CA ssh cube-node cat /root/.local/share/mkcert/rootCA.pem \ /etc/pki/ca-trust/source/anchors/cube-rootCA.pem # 安装到系统信任链 sudo update-ca-trust关键细节应使用CUBE_SSL_CERT_FILE而非直接覆盖SSL_CERT_FILE。e2b.py 中_ssl_context()上下文管理器只在 E2B SDK 调用期间临时设置SSL_CERT_FILE调用结束即恢复避免全局覆盖 Python 的 CA 证书包导致访问 HuggingFace 等公网站点时 SSL 验证失败。同理create_sandbox_info()也在函数作用域内临时设置并恢复。9.2 envd 注入envd 是静态链接的 x86_64 二进制约 15MB无外部依赖注入后必须设置为ENTRYPOINT [/usr/bin/envd]对应 envd-inject/Dockerfile 的ENTRYPOINT [/usr/bin/envd, -isnotfc]默认监听端口 49983创建模板时--expose-port 49983与--probe 49983均指向该端口。9.3 Kimi K2.5 thinking 模式Kimi K2.5 默认开启 thinking 模式与 LiteLLM 的 tool call 消息格式不兼容。需通过extra_body: {thinking: {type: disabled}}禁用否则多轮 tool call 会报reasoning_content is missing错误配置见 e2b-kimi.yaml。9.4 SWE-bench 镜像用户SWE-bench 镜像以 root 运行而 E2B SDK 默认使用user用户。必须在配置中指定user: root示例所有 YAML 的environment节均显式声明。9.5 常见故障排查scripts/README.md 收录了四类高频问题SSL 证书错误SSL: CERTIFICATE_VERIFY_FAILED原因通常是SSL_CERT_FILE被 mkcert 的rootCA.pem覆盖了系统 CA改用CUBE_SSL_CERT_FILE即可HuggingFace 数据集下载超时.env中设置HF_ENDPOINThttps://hf-mirror.comLLM API 连接失败用 curl 测试tokenhub.tencentmaas.com与api.deepseek.com的连通性模型端点不可用endpoint is inactiveTokenHub 上的模型端点被禁用或下线需登录后台确认模型状态残留沙箱实例评测异常退出后用 check-instances.sh 批量清理如bash scripts/check-instances.sh --template your-template-id --kill。10. 非目标与边界PRD 明确划定了本 Example 的范围边界以下内容不在本示例范围内RL 训练代码实现GRPO/PPO 等模型微调基础设施SWE-bench 全集评测仅演示单题生产环境部署方案。换句话说本示例交付的是评测即基础设施把 SWE-bench 单题评测打磨成可并发、可采样、可收集轨迹、可计算奖励的流水线RL 训练算法本身留给上层实现。结语本示例的价值在于打通了一条完整的链路从 SWE-bench 原始镜像注入 envd到注册为 cube-sandbox 模板再到通过 E2B SDK 驱动 mini-swe-agent 在秒级创建/销毁的沙箱中交互解题、提交 patch、完成评测。PRD 中的 RL 训练循环不是纸面设计——共享连接池、进程池批量建沙箱、沙箱预创建直连、TUI 观测面板这些并发采样所需的工程能力已经以源码形式存在于 e2b.py 与 run-concurrent.py 中。对于希望用轻量级沙箱构建 Agent 编程评测或 RL 训练数据流水线的团队本示例提供了可直接复用、可复制运行的完整参考实现。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 cube-sandbox 与 SWE-bench 评测：基于 E2B 兼容沙箱构建 LLM Agent 编程评测与 RL 训练基础设施
cube-sandbox 与 SWE-bench 评测基于 E2B 兼容沙箱构建 LLM Agent 编程评测与 RL 训练基础设施【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox本文对应仓库 examples/mini-rl-training 示例的完整需求文档PRD.mdv1.0并辅以该示例的源码补丁、配置与脚本作为实现级佐证。文中涉及的完整实操步骤可进一步参考 README_zh.md 与 scripts/README.md。导读本文讲解如何在 cube-sandbox 轻量级虚拟化平台上以SWE-bench软件工程基准测试为应用场景将 LLM Agentmini-swe-agent接入 E2B 兼容沙箱环境自动化解决真实 GitHub issue 并进行测试通过率评测。读完本文你将掌握cube-sandbox 与 E2B SDK 的兼容接入原理、mini-swe-agent 的 E2B 环境改造细节、从镜像注入 envd 到模板注册再到评测运行的完整操作链以及为后续 RL强化学习训练建立批采样、奖励计算与轨迹收集基础设施的设计思路。1. 项目背景cube-sandbox 与 E2B 兼容体系cube-sandbox是一个轻量级虚拟化平台其管理流和数据流完全兼容 E2B SDK。平台通过沙箱内的 agentenvd提供 gRPC 接口支持命令执行、文件读写和沙箱生命周期管理。这意味着任何基于 E2B SDK 编写的应用都可以无差别地运行在 cube-sandbox 之上。本示例以 SWE-bench 为落点演示了四个层层递进的能力使用 cube-sandbox 创建隔离的代码执行环境通过 E2B SDK 驱动 LLM Agent 在沙箱内交互式解题自动化评测 Agent 的解题能力为后续 RL强化学习训练建立基础设施。2. 目标从单题评测到 RL 训练闭环2.1 短期目标本 Example提供一个可运行的端到端示例覆盖从镜像准备到评测完成的全部环节支持多 LLM 模型切换Gemini、GLM、MiniMax、Kimi 等输出结构化的评测结果patch、步骤数、费用、耗时。2.2 长期愿景RL 训练循环PRD 将评测流水线进一步抽象为完整的 RL 训练循环┌─────────────────────────────────────────────────────────────────┐ │ RL Training Loop │ │ │ │ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Policy │ │ Action │ │ Env │ │ Reward │ │ │ │ (LLM) │───►│ bash 命令 │───►│ E2B 沙箱 │───►│ 测试通过率│ │ │ │ │◄───│ │◄───│ testbed │◄───│ │ │ │ └──────────┘ └───────────┘ └──────────┘ └──────────┘ │ │ ▲ │ │ │ └────────────── Policy Update ◄──────────────────┘ │ └─────────────────────────────────────────────────────────────────┘该循环与 RL 概念的一一对应关系正是本示例被设计为RL 训练基础设施的根本原因RL 概念对应实现Environmentcube-sandbox 沙箱通过 E2B SDK 管理Statetestbed 中的代码仓库状态 命令历史ActionAgent 生成的 bash 命令RewardSWE-bench 测试通过率0 或 1PolicyLLM可通过 RL 微调优化3. 系统架构3.1 整体拓扑┌─────────────────┐ ┌──────────── cube-sandbox ────────────┐ │ │ │ │ │ mini-swe-agent │ E2B SDK │ ┌──────────────┐ │ │ (LLM Agent) │─────────►│ │ envd │──► bash 命令执行 │ │ │ HTTPS/ │ │ :49983 │──► 文件读写 │ │ ┌───────────┐ │ gRPC │ └──────────────┘ │ │ │ LiteLLM │ │ │ │ │ │ ┌──────┐ │ │ │ ┌──────────────────────────────┐ │ │ │ │Gemini│ │ │ │ │ /testbed │ │ │ │ │GLM-5 │ │ │ │ │ (SWE-bench repo testcase) │ │ │ │ │Kimi │ │ │ │ └──────────────────────────────┘ │ │ │ │... │ │ │ │ │ │ │ └──────┘ │ │ └───────────────────────────────────────┘ │ └───────────┘ │ └─────────────────┘3.2 关键组件组件说明mini-swe-agent开源 LLM Agent 框架支持多轮 tool call 交互LiteLLM统一 LLM API 接口支持 OpenAI、Gemini、TokenHub 等E2B SDKPython 客户端通过Sandbox类管理沙箱生命周期envdcube-sandbox 的 in-sandbox agent静态链接二进制监听:49983SWE-bench软件工程基准测试集包含真实 GitHub issue 测试用例3.3 E2B SDK 接口示例中实际用到的 E2B SDK 接口可归纳为五类操作接口功能Sandbox(template...)从模板创建沙箱sbx.commands.run(cmd, user...)执行 bash 命令sbx.files.read(path)读取文件内容sbx.files.write(path, content)写入文件sbx.files.list(dir)列出目录sbx.kill()销毁沙箱需要说明本示例的评测场景主要使用commands.run执行 shell 命令文件读写接口则面向更通用的 Agent 文件操作场景。在仓库的并发压测模式benchmark中还会用echo ok作为沙箱创建/销毁的验证命令见 scripts/README.md。4. mini-swe-agent 改造为 LLM Agent 接入 E2B 沙箱mini-swe-agent 原生支持 Docker、Singularity 等执行环境但不支持 E2B。为接入 cube-sandbox需要对 mini-swe-agent 做最小化改造。改造后的补丁代码位于 mini-swe-agent-patch。4.1 修改的文件文件改动environments/extra/e2b.py新增— E2B 环境类封装 E2B SDK 的沙箱操作environments/__init__.py注册e2b到环境类型映射表_ENVIRONMENT_MAPPINGrun/benchmarks/swebench.py在get_sb_environment中将e2b加入支持image参数的类型列表安装补丁的方式先安装 mini-swe-agent再运行补丁脚本将文件覆盖到 site-packagespip install mini-swe-agent[extra] bash install.sh4.2 E2BEnvironment 类实现核心实现位于 environments/extra/e2b.py约 130 行 Python。配置类E2BEnvironmentConfig基于 pydanticBaseModelclass E2BEnvironmentConfig(BaseModel): template_id: str # E2B 模板 ID或从 CUBE_TEMPLATE_ID 环境变量读取 image: str # SWE-bench 兼容字段实际不使用 cwd: str /testbed # 工作目录 timeout: int 60 # 单条命令超时秒 user: str root # 执行用户 sandbox_timeout: int 1800 # 沙箱生命周期秒核心方法方法功能__init__通过Sandbox.create(templatetemplate_id)创建 E2B 沙箱execute(action)拼接cd {cwd} {command}通过sbx.commands.run()执行合并 stdout/stderr_check_finished(output)检测输出首行是否为COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT若是则抛出Submitted异常触发提交cleanup()调用sbx.kill()销毁沙箱释放资源命令执行流程Agent 发出 action {command: grep -r def _build_app_dict .} │ ▼ E2BEnvironment.execute() │ 拼接: cd /testbed grep -r def _build_app_dict . ▼ sandbox.commands.run(full_cmd, userroot, timeout60) │ 通过 HTTPS/gRPC 发送到 envd ▼ envd 在沙箱内执行 bash 命令 │ ▼ 返回 {output, returncode, exception_info} │ ▼ _check_finished() 判断是否提交 patch结合源码可以看到几个值得注意的细节提交协议_check_finished要求输出首行恰好为COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT且returncode 0此时将剩余行作为submission随Submitted异常抛出raise Submitted({...})交由 Agent 框架完成 patch 提交。超时自愈execute捕获TimeoutError后先cleanup()销毁沙箱再重新抛出避免超时命令污染后续状态。异常归一化普通命令异常被包装为{output, returncode: -1, exception_info}结构并附带exception_type/exception字段供上层观测模板渲染。4.3 环境注册在environments/__init__.py的_ENVIRONMENT_MAPPING中添加一行_ENVIRONMENT_MAPPING { docker: ..., singularity: ..., # ... e2b: minisweagent.environments.extra.e2b.E2BEnvironment, # 新增 }4.4 SWE-bench 入口适配在run/benchmarks/swebench.py的get_sb_environment()中将e2b加入支持image参数的环境列表if env_config[environment_class] in [docker, swerex_modal, e2b]: env_config[image] image_name这样 SWE-bench 运行器会自动将题目对应的 Docker 镜像名传给 E2B 环境配置E2B 环境类内部忽略image字段使用template_id。4.5 源码级深入并发与性能优化e2b.py 在 PRD 描述的基础实现之上还包含面向大规模并行评测的三处关键设计这是把评测流水线推向 RL 训练基础设施的关键① 共享 HTTP 连接池。默认 E2B SDK 每次创建/销毁沙箱都会新建httpx.Client与 TCP 连接产生重复的 TCP TLS 握手开销。_get_shared_api_client()用单例 锁的方式复用一个连接池Limits(max_connections50, max_keepalive_connections50, keepalive_expiry300)使 keep-alive 连接在多次 API 调用间复用。② 沙箱预创建SandboxInfo。create_sandbox_info()是独立的顶层函数仅负责通过POST /sandboxes创建沙箱并返回连接信息sandbox_id、sandbox_domain、envd_version、envd_access_token、api_call_ms随后E2BEnvironment可通过_connect_existing()直接连上已存在的沙箱跳过创建 API 调用。batch_create_sandboxes()进一步用ProcessPoolExecutor默认 8 worker并行预创建一批沙箱——每个 worker 进程持有独立的连接池规避 GIL 限制实现真正的并行创建。失败条目以None占位不影响整体进度。③ 进程退出兜底清理。模块通过atexit.register与SIGINT/SIGTERM信号处理器注册_cleanup_all_sandboxes()用weakref跟踪所有活跃沙箱保证评测进程异常退出时不残留实例。5. 核心流程5.1 镜像准备SWE-bench 原始镜像 ──► envd 注入 ──► 注册为 cube-sandbox 模板从cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest提取 envd 二进制境外访问请使用cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest将 envd 注入 SWE-bench 镜像Dockerfile 覆盖 ENTRYPOINT将注入后的镜像注册为 cube-sandbox 模板获得template_id。envd 注入的实际 Dockerfile 位于 envd-inject/DockerfileARG BASE_IMAGE FROM ${BASE_IMAGE} COPY envd /usr/bin/envd RUN chmod x /usr/bin/envd ENTRYPOINT [/usr/bin/envd, -isnotfc]可以看到 envd 被放置到/usr/bin/envd并作为容器ENTRYPOINT带-isnotfc参数这正是 PRD 中注入后必须设置为ENTRYPOINT [/usr/bin/envd]约束的落地实现。日常使用无需手工构建仓库已提供预构建的公开镜像已注入 envd可直接从cube-sandbox-image.tencentcloudcr.com/demo/django_1776_django-13447:latest拉取。如需为其他 SWE-bench 题目注入 envd可运行 scripts/inject-envd.shbash scripts/inject-envd.sh swebench/sweb.eval.x86_64.django_1776_django-13447:latest脚本会将源镜像与注入后的新镜像推送到镜像仓库随后即可用cubemastercli创建模板cubemastercli tpl create-from-image \ --image cube-sandbox-image.tencentcloudcr.com/demo/django_1776_django-13447:latest \ --writable-layer-size 1G \ --expose-port 49983 \ --cpu 4000 \ --memory 8192 \ --probe 49983参数说明--image已注入 envd 的 SWE-bench 镜像地址--writable-layer-size可写层大小沙箱内文件修改空间--expose-portenvd gRPC 端口固定 49983--cpuCPU 配额毫核4000 4 核--memory内存配额MB8192 8G--probe健康检查端口与 expose-port 一致命令输出的template_id填入.env的CUBE_TEMPLATE_ID。注意这里同时暴露了--expose-port与--probe均为 envd 监听端口 49983——envd 的连通性检查通过该端口的探活完成。5.2 评测流程加载 SWE-bench 题目 │ ▼ 创建 E2B 沙箱template_id │ ▼ ┌──────────────────────┐ │ Agent 交互循环 │ │ ① LLM 分析问题 │ │ ② 生成 bash 命令 │ │ ③ E2B 执行命令 │ │ ④ 返回结果给 LLM │ │ ⑤ 重复直到提交 patch │ └──────────────────────┘ │ ▼ 提取 patch 评估结果 │ ▼ 销毁沙箱5.3 RL 训练扩展愿景在评测流程基础上增加四件事即可升级为 RL 训练循环Batch 采样并行创建多个沙箱同一题目多次尝试Reward 计算reward 1 if tests_pass else 0可扩展为部分分Trajectory 收集记录 (state, action, reward) 序列Policy Update使用 GRPO/PPO 等算法更新 LLM 权重。PRD 明确了 cube-sandbox 在此场景下的三点优势沙箱创建/销毁开销低秒级适合大规模并行采样E2B SDK 兼容性确保与主流工具链无缝集成envd 无依赖注入支持任意 Linux 镜像。从仓库现状看并发基础设施沙箱预创建、进程池批量创建、共享连接池已经在 run-concurrent.py 与 e2b.py 中落地RL 训练本身GRPO/PPO 实现被明确列为非目标。6. 快速开始从依赖安装到单题评测6.1 前置条件Python 3.10Docker用于构建 envd 注入镜像cube-sandbox 平台访问权限API URL API Key至少一个 LLM API KeyGemini / TokenHub / OpenAI 等6.2 安装依赖与补丁pip install -r requirements.txt bash mini-swe-agent-patch/install.sh也可以使用 scripts/setup-env.sh 一键完成 Python 版本检查、依赖安装、库验证与.env初始化。6.3 配置环境变量cp .env.example .env关键变量对应 README_zh.md 的 Step 3# HuggingFace 镜像国内网络使用 hf-mirror.com 避免超时 HF_ENDPOINThttps://hf-mirror.com # cube-sandbox 平台连接信息 E2B_API_URLhttp://your-cube-sandbox-ip:3000 E2B_API_KEYyour-api-key # SWE-bench 镜像模板 ID CUBE_TEMPLATE_IDyour-template-id # SSL 证书自部署平台需要仅作用于 E2B SDK 连接 CUBE_SSL_CERT_FILE/etc/pki/tls/cert.pem # LLM API Key选择一个或多个 GEMINI_API_KEYyour-gemini-key TOKENHUB_API_KEYyour-tokenhub-key OPENAI_API_KEYyour-openai-key注意template_id的解析顺序是配置 YAML 中environment.template_id优先其次才是环境变量CUBE_TEMPLATE_ID对应 e2b.py 中self.config.template_id or os.environ.get(CUBE_TEMPLATE_ID, )的逻辑。6.4 运行单次评测使用 Gemini 3 Flash 解决django__django-13447bash scripts/run-swebench.sh \ --model gemini/gemini-3-flash-preview \ --instance django__django-13447 \ --config configs/e2b-swebench.yamlrun-swebench.sh 的主要参数参数必填默认值说明--model✅LLM 模型名如deepseek/deepseek-chat--instance✅SWE-bench 实例 ID如django__django-13447--configconfigs/e2b-swebench.yamlYAML 配置文件--subsetlite数据集子集lite/verified/full--splittest数据集分割test/dev--step-limit配置文件中的值最大 Agent 步数覆盖配置文件--outputresults/输出目录运行结果保存在results/model/instance/下包含trajectory.jsonAgent 交互轨迹与run.log运行日志。6.5 基础配置剖析e2b-swebench.yaml 展示了三类核心配置agentsystem/instance 提示词模板、step_limit: 100、cost_limit: 3.0、mode: yoloenvironmentcwd: /testbed、timeout: 60、user: root、environment_class: e2b——注意 SWE-bench 镜像以 root 运行因此必须显式指定user: rootmodelobservation_templateJinja2 模板控制如何把命令输出、returncode、异常信息回传给 LLM超过 10000 字符的输出会被截断为 head/tail 各 5000 字符并提示 elided 字符数、format_error_template、model_kwargs。observation_template与_check_finished共同构成了 Agent 与沙箱之间的观察-提交协议普通输出按 returncode/异常/正文三段回传而首行为提交标记的输出则触发Submitted异常进入 patch 提交路径。7. 多模型切换与并发评测7.1 多模型切换示例通过 LiteLLM 统一模型名并准备了多套配置模型命令示例配置文件Gemini直连--model gemini/gemini-3-pro-previewe2b-swebench.yamlGLM-5 / MiniMax / DeepSeek V3.2TokenHubexport OPENAI_API_KEY$TOKENHUB_API_KEY; --model openai/glm-5e2b-tokenhub.yamlKimi K2.5 / DeepSeek R1 / 混元 ThinkingTokenHub需禁用 thinking--model openai/kimi-k2.5e2b-kimi.yamlDeepSeek Chat直连--model deepseek/deepseek-chate2b-deepseek.yamlDeepSeek Reasoner直连禁用 thinking--model deepseek/deepseek-reasonere2b-deepseek-reasoner.yamlTokenHub 与 DeepSeek 直连配置的区别仅在model_kwargs.api_basehttps://tokenhub.tencentmaas.com/v1与https://api.deepseek.com普通模型配置drop_params: trueparallel_tool_calls: true。7.2 Thinking 模型的特殊处理Kimi K2.5 等 Thinking 模型默认开启思考模式其reasoning_content与 LiteLLM 的 tool call 消息格式不兼容多轮 tool call 会报reasoning_content is missing错误。解决方式是在配置中显式禁用 thinking见 e2b-kimi.yamlmodel: model_kwargs: api_base: https://tokenhub.tencentmaas.com/v1 drop_params: true parallel_tool_calls: true extra_body: thinking: type: disabled7.3 高并发评测与纯沙箱压测run-concurrent.py 提供两种模式benchmark纯沙箱创建/销毁吞吐压测无需 LLM如python scripts/run-concurrent.py benchmark -w 50 -n 100 --keep50 并发创建 100 个沙箱并保留不销毁swebench高并发评测支持--repeat同题多次、--pre-create进程池预创建沙箱任务启动即直连、--template-map实例到模板的 JSON 映射。常用参数参数说明-m模型名逗号分隔多个或tokenhub表示全部 TokenHub 模型--repeat N每个模型重复 N 次--pre-create多进程预创建沙箱任务启动时直连--pre-create-workers N预创建并发数-w N任务执行并发数--step-limit N限制 Agent 最大步数--sandbox-only跳过 LLM纯沙箱压测--max-rows NTUI 显示行数0显示全部多实例映射通过 template-mapping.json 提供未列出的实例回退到.env中的CUBE_TEMPLATE_ID。该工具还内建实时 TUI 仪表盘Header/Stats/Tasks/cubecli ls 面板可观测每个任务的创建耗时分布avg/p50/p95/max与总 Cost运行结束输出创建耗时直方图与失败任务明细——这正是 RL 批量采样所需的观测能力。8. 已验证结果8.1 多模型评测django__django-13447E2B 沙箱环境模型步骤费用耗时结果Kimi K2.542$0.93179 秒成功Gemini 3 Pro22$0.26224 秒成功Gemini 3 Flash46$0.19278 秒成功MiniMax M2.756$1.62363 秒成功GLM-541$0.75400 秒成功上述数据来自 PRD v1.0 的已验证结果章节测试题目为django__django-13447README_zh.md 中另有 DeepSeek Chat35 步 / $0.02 / 253s成功与 DeepSeek Reasoner75 步 / $0.05 / 389s成功的记录其余模型标注待测。这些是仓库内记录的实测数据读者可在自己的平台环境中复现验证。8.2 Docker 直连 vs E2B 沙箱Gemini 3 Flash, django__django-13447指标Docker 直连E2B 沙箱差异耗时208 秒278 秒34%步骤49 步46 步-6%费用$0.16$0.1919%PRD 指出E2B 额外耗时主要来自沙箱创建网络开销和 HTTPS/gRPC 传输延迟整体性能损耗在可接受范围内。从实现层面看这也是 e2b.py 引入共享连接池与沙箱预创建的直接动机——通过复用连接与并行创建可以进一步压缩沙箱创建网络开销这一占比。9. 技术约束与注意事项9.1 SSL 证书自部署 cube-sandbox 使用 mkcert 证书客户端需要安装 cube-sandbox 节点的 root CA 到系统信任链设置SSL_CERT_FILE环境变量指向系统证书包Python httpx/certifi 需要。实操上从 cube-sandbox 节点导出 root CA 并安装# 从 cube-sandbox 节点获取 root CA ssh cube-node cat /root/.local/share/mkcert/rootCA.pem \ /etc/pki/ca-trust/source/anchors/cube-rootCA.pem # 安装到系统信任链 sudo update-ca-trust关键细节应使用CUBE_SSL_CERT_FILE而非直接覆盖SSL_CERT_FILE。e2b.py 中_ssl_context()上下文管理器只在 E2B SDK 调用期间临时设置SSL_CERT_FILE调用结束即恢复避免全局覆盖 Python 的 CA 证书包导致访问 HuggingFace 等公网站点时 SSL 验证失败。同理create_sandbox_info()也在函数作用域内临时设置并恢复。9.2 envd 注入envd 是静态链接的 x86_64 二进制约 15MB无外部依赖注入后必须设置为ENTRYPOINT [/usr/bin/envd]对应 envd-inject/Dockerfile 的ENTRYPOINT [/usr/bin/envd, -isnotfc]默认监听端口 49983创建模板时--expose-port 49983与--probe 49983均指向该端口。9.3 Kimi K2.5 thinking 模式Kimi K2.5 默认开启 thinking 模式与 LiteLLM 的 tool call 消息格式不兼容。需通过extra_body: {thinking: {type: disabled}}禁用否则多轮 tool call 会报reasoning_content is missing错误配置见 e2b-kimi.yaml。9.4 SWE-bench 镜像用户SWE-bench 镜像以 root 运行而 E2B SDK 默认使用user用户。必须在配置中指定user: root示例所有 YAML 的environment节均显式声明。9.5 常见故障排查scripts/README.md 收录了四类高频问题SSL 证书错误SSL: CERTIFICATE_VERIFY_FAILED原因通常是SSL_CERT_FILE被 mkcert 的rootCA.pem覆盖了系统 CA改用CUBE_SSL_CERT_FILE即可HuggingFace 数据集下载超时.env中设置HF_ENDPOINThttps://hf-mirror.comLLM API 连接失败用 curl 测试tokenhub.tencentmaas.com与api.deepseek.com的连通性模型端点不可用endpoint is inactiveTokenHub 上的模型端点被禁用或下线需登录后台确认模型状态残留沙箱实例评测异常退出后用 check-instances.sh 批量清理如bash scripts/check-instances.sh --template your-template-id --kill。10. 非目标与边界PRD 明确划定了本 Example 的范围边界以下内容不在本示例范围内RL 训练代码实现GRPO/PPO 等模型微调基础设施SWE-bench 全集评测仅演示单题生产环境部署方案。换句话说本示例交付的是评测即基础设施把 SWE-bench 单题评测打磨成可并发、可采样、可收集轨迹、可计算奖励的流水线RL 训练算法本身留给上层实现。结语本示例的价值在于打通了一条完整的链路从 SWE-bench 原始镜像注入 envd到注册为 cube-sandbox 模板再到通过 E2B SDK 驱动 mini-swe-agent 在秒级创建/销毁的沙箱中交互解题、提交 patch、完成评测。PRD 中的 RL 训练循环不是纸面设计——共享连接池、进程池批量建沙箱、沙箱预创建直连、TUI 观测面板这些并发采样所需的工程能力已经以源码形式存在于 e2b.py 与 run-concurrent.py 中。对于希望用轻量级沙箱构建 Agent 编程评测或 RL 训练数据流水线的团队本示例提供了可直接复用、可复制运行的完整参考实现。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考