文档
按仓库分类。每一行的主文字是文档名，路径在下面。中文和 English 切换同一篇的两个版本；只有一种语言的会留下来，并注明。点进去是渲染后的 Markdown，站外链接会新开标签。常见问题写在本站。
本站
CLI
.agents/ — engineering record of the cli repositoryMaintainer and AI-agent facing records of why the CLI looks the way it does. Nothing here is published to npm2026-10-13 差分分组（相对 Python abx 0.2.0）Oracle：/tmp/venv-orig/bin/abx（Python abx 0.2.0）。对照日志在 /tmp/diff-fast/，本文件不改那五份日志。abx 黑盒 E2E 测试套件与语言无关的 abx CLI 黑盒端到端套件。它像真实用户一样启动被测二进制(argv、环境变量、stdin、退出码、Adversarial review logIndex of review rounds under parity/review/. Coordinators fill Findings and Fix status; builders do not close…Adversarial review: area agent-templateScope: port cli/src/agent/ (qwen_code, clarify, codegen, adopt, coding_agent, template_guide, dockerfile_sour…Adversarial review: area commandsScope: cli/src/framework/, cli/src/cli/{main,output,formatters,region,repl,scaffold,_rich,_orjson}.ts, cli/sr…Adversarial review: area coreScope: cli/src/{models,utils,transport,protocol,api,session}/ against Python agent_sandbox/{models,utils,tran…Agent Sandbox[](https://github.com/alibaba-agent-sandbox/agent-sandbox/actions/workflows/ci.yml)Agent SandboxCLI (abx, Node.js/TypeScript) for the Alibaba Cloud FC Agent Sandbox service;Agent Sandbox CLI — 文档中心abx 是 Agent Sandbox 云端沙箱服务（阿里云函数计算）的命令行客户端：创建与管理沙箱、执行代码与命令、编写与部署模板，并通过 MCP Server 向 IDE Agent 暴露沙箱。本页索引 CLI（@…Agent Sandbox CLI — 设计文档索引版本：v3.0 | 最后更新：2026-10-12Agent Sandbox Documentation中文文档 → docs/zh/Agent Sandbox — Agent Usage Guidename: agent-sandboxAgent Sandbox's command-line interface (a…Agent Sandbox's command-line interface (abx) is a terminal program. There is no graphical window in this repo…Agent Skill 安装与分发本指南说明如何把 Agent Sandbox 的 Agent Skill（仓库根目录的 SKILL.md）引入你的 AI 编码工具——Qoder、Claude Code、Cursor、Qwen Code、Codex 以…AGENTS.md — AI Contributor Entry PointFor AI coding assistants (Cursor, Copilot, Codex, Qoder, etc.).All notable changes to this project will…All notable changes to this project will be documented in this file.Blocked testsCurrent status: nothing is blocked.CLI / MCP / Testing — Comprehensive Design Reference (historical snapshot)⚠️ DEPRECATED DIRECTORY — .agents/design/ is no longer an active directory.CLI E2E baseline: Python oracle (abx 0.2.0, original Python implementation)Historical record of one dated run against the original Python implementation. The scenario suite has changed…CLI evidence snapshotsGolden-file regression tests for the exact text the CLI prints.CLI Evidence: Configstderr:CLI Evidence: Createstderr:CLI Evidence: DownloadCLI Evidence: Errorstderr:CLI Evidence: Execstderr:CLI Evidence: HelpCLI Evidence: InfoCLI Evidence: Killstderr:CLI Evidence: ListCLI Evidence: McpCLI Evidence: Templatestderr:CLI Evidence: UploadCLI Evidence: VersionCLI 参考手册每个动作只有一条规范的 abx GROUP VERB 路径，外加一小组固定的顶层快捷方式。完整命令树、用法行和已移除写法见CLI 命令参考（规范命令树）；本页记录各命令的选项。CLI 命令体系设计abx CLI 是 Agent Sandbox 的命令行入口，兼顾人类开发者和 AI Agent 两种使用场景。CLI 的终极目标：用户不需要知道模板、资源规格、配置参数，只需要描述想做什么，sandbox 自动搞定一…CLI 命令参考（规范命令树）每个操作只有一个规范路径，写作 abx 组 动词。在此之上只有一小组固定的顶层快捷方式，对应最常用的命令。CLI 教程本教程带你从安装开始，逐步掌握 abx CLI 的完整沙箱生命周期、模板使用和 MCP 集成。CLI 架构设计本文描述 Node.js / TypeScript 实现的 abx CLI（@agent-sandbox/cli）本身：分层结构、源码目录、构建与发布方式。命令级行为见Completeness review: CLI port (Python abx -> cli/src)Method: mechanical inventories, not sampling. Everything below is regenerated byCompleteness review: the project split (original single repo -> cli/ + python-sdk/{client-sdk,server-sdk})Inventory source: every git-tracked file of the original repo (622 files) classified byDecision: @sandbox.register decorator-based command (registered on the persistent HTTP server endpoint)Status: implementedDecision: abx config delete removes one stored valueStatus: implementedDecision: abx config init collects the template-deploy prerequisitesStatus: implementedDecision: abx deploy is the fixed publish step; descriptions belong to template authoringStatus: implementedDecision: abx run (Named Commands) vs abx exec (Raw Shell)Status: supersededDecision: abx template init --adopt — let the coding agent make an existing project deployableStatus: implementedDecision: Add access_key_id / access_key_secret to abx config setStatus: implementedDecision: Add CI environment variable suppression fixture in test conftestStatus: implementedDecision: Add guided configuration wizard (abx config init) to the abx CLIStatus: implementedDecision: AI-generated templates ship a SandboxServer entry pointStatus: implementedDecision: Allow template.yaml name to differ from directory name for reserved namesStatus: implementedDecision: Ask for a directory on natural-language initStatus: implementedDecision: Black-box E2E suite, differential harness and Definition of DoneStatus: implementedDecision: Brand rename sbox → abxStatus: implementedDecision: Built-in Agent as CLI Syntax SugarStatus: implementedDecision: BYO agent integration — dedicated templates + custom_commands contract, no in-SDK agent runtimeStatus: implementedDecision: CLI command reduction (60+ → 43 commands)Status: supersededDecision: CLI Named abxStatus: implementedDecision: CLI repository layout and publishing as agent-sandbox/agent-sandboxStatus: proposedDecision: CLI Tool (abx)Status: implementedDecision: Command Source Resolution (Local Cache → Online Metadata Fallback)Status: supersededDecision: Configurable CLI Shortcuts via config.tomlStatus: implementedDecision: Converge init/create command semantics (remove top-level abx init, make create routing explicit)Status: implemented — partially superseded (2026-09-29) by 2026-09-29-init-restore-and-create-explicit-error.…Decision: Docs ownership audit — the cli repository documents only the CLIStatus: implementedDecision: Enforce 120s minimum timeout for sandbox creationStatus: implementedDecision: fixed command surface, one exec, server-only named commandsStatus: implementedDecision: Full audit and completion of CLI help textsStatus: implementedDecision: Integrate Qwen Code as the AI coding backend for the abx create NL pathStatus: implementedDecision: MCP FC Streamable HTTP TransportStatus: implementedDecision: Minimal Template Repository ShapeStatus: implementedDecision: Move --region from a global root option to command-level optionsStatus: implementedDecision: Natural-language template init, and a create-path switch to itStatus: implementedDecision: One CLI name per credentialStatus: implementedDecision: One resolution order for every credentialStatus: implementedDecision: Open-source hygiene sweep and check-no-local-paths guardStatus: implementedDecision: P0+P1 Overdesign CleanupStatus: implementedDecision: Plain-language hint for an invalid shortcut targetStatus: implementedDecision: Plug in coding-agent backends behind a protocol boundary (Qwen Code stays the default)Status: implementedDecision: Remove legacy declarative build fields from template.yamlStatus: implementedDecision: Research-first two-phase clarification (plain research round → structured assessment) on one native sessionStatus: implementedDecision: Restore the top-level abx init shortcut, make bare abx create an explicit error, and add unknown-command hintsStatus: implementedDecision: Rolling agent-activity lines under the progress headerStatus: implementedDecision: Separate CLI result output from progress and log channelsStatus: implementedDecision: Single-question clarification loop for the abx create NL pathStatus: implementedDecision: Single-repo single-distribution + [cli] extra (no split, no binary for now)Status: supersededDecision: Skills Design Removal and MCP Docs ConvergenceStatus: implementedDecision: Static SKILL.md Agent Guide at the Repository RootStatus: implementedDecision: Stream build and push logs under the step headerStatus: implementedDecision: Tag-triggered npm release workflow replaces the release-event publish workflowStatus: implementedDecision: Template Awesome — community sandbox template indexStatus: implementedDecision: Template Catalog Single Source of Truth (awesome-templates)Status: implementedDecision: template command redesignStatus: implementedDecision: template deploy one-shot deployment commandStatus: implementedDecision: Unify the qwen-code session-turns parameter name and semanticsStatus: implementedDefinition of DoneThis is the binding product-owner rule for this repository. It is not an ADR (it has no Status); itDifferential fast harnesses (2026-10-12)Oracle: ORACLE_VENV=/tmp/venv-orig (/tmp/venv-orig/bin/abx present). Commands from cli/: node parity/diff/{sa…FC Sandbox 自定义模板部署 E2E 验证⚠️ HISTORICAL SNAPSHOT / 历史验证快照 — 标注追加于 2026-09-24（任务 #122，承接 #109 审计）Integration testsPorts of the Python tests/integration/_e2e.py files. The split follows the Python @pytest.mark.integration ma…Known gapsThe CLI has a fixed command surface that the Python CLI does not have. Python tests for the removed behavior…MCP Server 设计Agent Sandbox MCP Server 将沙箱能力暴露为 MCP (Model Context Protocol) Tools，让 AI Agent（Cursor、Claude Desktop、VS Code…MCP 与 AI Agent 集成调研文档版本：v1.0 | 最后更新：2026-09-01MCP 集成Agent Sandbox 提供 MCP（Model Context Protocol）Server，使 AI IDE 和工具能够直接操作沙箱。mock 对比 oracle 差分工具对两个 abx 二进制运行完全相同的 argv,并比较所有可观察结果:退出码、规范化后的 stdout/stderr、写入的文件Module Specifications & Architecture DecisionsThis directory contains Architecture Decision Records (ADRs) and module specificationsPoint-in-time artifacts that back decisio…Point-in-time artifacts that back decisions in ../notes/. They are kept verbatim and are notPorting contract: Python abx -> Node.js abxThe original project (github.com/alibaba-agent-sandbox/agent-sandbox @ b15b88f, v0.2.0) shipped the CLI as pa…Pre-design research owned by the CLI repo…Pre-design research owned by the CLI repository.Provider wiring plan (follow-up edits to existing CLI modules)Status (2026-10-13): wiring is done for the sandbox path; this file is now the record of the plan plus the li…Provider 端到端测试方案所有 provider，包括 OpenSandbox，都用同一套分级。跑不了的层级记为 skip 并写明原因，不算通过。Providers and Credentials (CLI spec) — review logReviewed document: providers-and-credentials-cli.md.Providers and Credentials — CLI spec (for the Node.js abx)Audience: the CLI worker who applies this spec.Python Hello 模板Fixture：本目录是主仓库的离线测试夹具（client-sdk/tests/test_templates/ 使用），Python SDK defect fixes the Node API layer must replicate (after the parity gate)The Python SDK (python-sdk/client-sdk) fixed the defects python-sdk/e2e/KNOWN-ISSUES.md records asqwencli 融入状态 + .agents/design 文档沉淀审计⚠️ SUPERSEDED / 历史快照（HISTORICAL SNAPSHOT） — 标注追加于 2026-09-24（任务 #122，承接 #109 审计；正文未改写）Repository Layout Review: the cli repositoryStatus: recommendation (architecture review, 2026-10-12). Maintainer-facing, English only. This is theReview area: completeness - did the port / split omit or degrade anything?Reviewer: independent (did not write the port). Scope: whole project split (Python CLI -> Node port, original…SDK 缺陷修复的真实云端验证(KI-001 .. KI-008)English: README.md.Verification: black-box E2E suite and differential harness (cli)Date: 2026-10-12Verification: CLI capability black-box E2EDate: 2026-10-12Verification: every abx command, black-boxDate: 2026-10-12Verification: OpenSandbox through the provider abstraction (TS CLI and Python SDK)Date: 2026-10-13Writing abx command modulesThis directory holds the command modules of the CLI (sandbox.ts, sandbox_files.ts, sandbox_process.ts,{{{{{{{{{{{{二进制安装abx 同时以预编译独立二进制的形式发布 —— 单个可执行文件内嵌了从零构建模板到沙箱使用：端到端指南本指南带你完成一个自定义沙箱模板从编写到生产使用的完整工作流。使用模板模板是预配置的沙箱环境定义，包含基础镜像、预装软件、能力声明和自定义命令。常见问题（FAQ）1. 检查网络：确认可以访问 api.cn-hangzhou.e2b.fc.aliyuncs.com快速入门本教程将带你完成从安装到销毁的完整沙箱生命周期。提供商（Providers）提供商 是一个沙箱后端。abx 内置一个提供商，并可通过可安装的插件驱动更多后端。本页是 CLI 视角：如何在命令行安装、选择、配置并使用提供商。共享概念（清单、信任模型、EPP/1 协议、能力矩阵）只在 Python…提供方与凭证 —— CLI 规格评审记录被评审的文档：providers-and-credentials-cli.md。它是 Python SDK 设计的 CLI 对应文档；SDK 一侧的评审（两轮，附流程说明）见 python-sdk/docs/zh/de…提供方与凭证 —— CLI 规格（Node.js abx）读者：落实本规格的 CLI 实现。提供方接线计划（对现有 CLI 模块的后续修改）状态（2026-10-13）：沙箱路径的接线已经完成；本文现在是原计划的记录，加上仍未解决的事项清单。provider 已是命令组，--provider / --opt / --all-providers 和带前缀的…操作指南二进制注册五个命令组：sandbox、template、config、mcp、provider。deploy 是顶层快捷方式，不是命令组。每一行是做这件事时要运行的那一条命令。旗标、退出码和完整选项在链接的参考里。最佳实践该用哪个开关。命令写法在 CLI 参考 和操作指南。模板目录（Templates Catalog）设计模板目录采用单一事实来源（SSOT）架构：官方与社区模板的内容、机器可读索引沙箱中的环境变量（CLI）本指南说明如何通过 abx CLI 在沙箱内设置和读取环境变量，以及发送给沙箱的命令适用哪些执行规则。底层模型——每个沙箱内有两个相互独立的进程作用域——对 CLI 和 Python SDK 是一致的；包含 SDK 与…测试与完成定义abx 如何做端到端验证,以及判定一项变更"算完成"的规则。编写提供商提供商插件是一个目录，包含 abx-provider.toml 清单；对于 exec 类型，还包含一个使用 EPP/1（JSON-RPC 2.0，stdin/stdout，每行一个 JSON 对象）通信的程序。同一个插…编写模板本文档介绍如何创建自定义 Agent Sandbox 模板，包括目录结构、改造已有项目以及通过 CLI 发布。认证详解Agent Sandbox 支持两种认证模式：API Key 和 AK/SK（阿里云 AccessKey）。过度设计 / 合理性 / 优化审计报告⚠️ SUPERSEDED / 历史快照（HISTORICAL SNAPSHOT） — 标注追加于 2026-09-24（任务 #122，承接 #109 审计；正文未改写）部署与构建本指南介绍 CLI 的构建与发布工作流：模板生命周期（abx template init → abx deploy → abx create）。Python SDK 不构建也不部署任何东西，它只负责启动结果（见相关 S…配置参考本文档列出 Agent Sandbox 的所有配置项、环境变量、默认值和优先级规则。错误码参考所有 SDK 错误都继承自 SandboxError，携带 code（错误码）、message（消息）、suggestion（建议）、docs_url（文档 URL）属性。
Python SDK
.agents/ — engineering record of the python-sdk repositoryMaintainer and AI-agent facing records of why the code looks the way it does. Nothing here is imported or01 - 原则、范围与非目标状态：归档。不是现行规范。02 - 操作模型状态：归档。不是现行规范。03 - 策略与权限状态：归档。不是现行规范。04 - 内置模块与操作目录状态：归档。不是现行规范。05 - 作为内置能力的 Agents API状态：归档。不是现行规范。06 - 延迟安装、清单与 agent-sandbox-server 命令状态：归档。不是现行规范。07 - 客户端镜像：Python ServerClient 与 Node CLI状态：归档。不是现行规范。08 - 模板构建体验状态：归档。不是现行规范。09 - 面向 AI 写配置的可用性状态：归档。不是现行规范。abx CLI 跟进项：细粒度能力、基础镜像、服务端对齐状态：归档。不是现行规范。Agent Sandbox[](https://github.com/alibaba-agent-sandbox/python-sdk/actions/workflows/ci.yml)Agent SandboxPython SDK for the Alibaba Cloud FC Agent Sandbox service.Agent Sandbox Documentation中文文档 → docs/zh/Agent Sandbox SDK — 文档中心Agent Sandbox 是可切换提供方的沙箱 SDK。默认提供方是阿里云极速版（函数计算）。同一套 API 还有 Modal 风格的 @sandbox 装饰器，以及沙箱内的 Agents API（Codex 与 Q…Agent Sandbox — ExamplesExamples are split by which package they exercise.Agent Sandbox — 使用示例示例按它们用的是哪一个包分开。Agent Sandbox — 设计文档索引版本：v2.0 | 最后更新：2026-09-24Agents API沙箱里的 HTTP 会话。70 条路由全部已实现。有本地后端的运行时有两个：Codex 和 Qwen Code。claude-code、cursor 和 command 是已声明、没有本地后端的适配器，GET /v1/…Agents API 参考沙箱服务端在 agents 能力组打开之后提供的全部 HTTP 接口。组默认关闭。下面 70 条路由全部已实现，每条都有测试。有本地后端的运行时只有两个：Codex（二进制 codex）和 Qwen Code（二进制…Agents API 设计：对抗式评审记录状态：归档。不是现行规范。Agents API：在 Agent Sandbox 里托管编码 Agent状态：现行设计AGENTS.md — AI Contributor Entry PointFor AI coding assistants (Cursor, Copilot, Codex, Qoder, etc.).AGENTS.md 对抗审计报告⚠️ SUPERSEDED / 历史快照（HISTORICAL SNAPSHOT） — 标注追加于 2026-09-24（任务 #122，承接 #109 审计；正文未改写）AI-Native Open-Source Completeness Audit⚠️ SUPERSEDED / HISTORICAL SNAPSHOT — annotation added 2026-09-24 (task #122, following the #109 audit; body…All notable changes to this project will…All notable changes to this project will be documented in this file.API 参考本文档列出 Agent Sandbox Python SDK 的全部公开 API 签名、参数、返回值和异常。Client SDKClient SDK. This package runs on your machine: create a sandbox, use it, and kill it. The HTTP service inside…Client SDKClient SDK 跑在你的机器上。它创建沙箱、连上已经存在的沙箱，然后在沙箱里执行命令、读写文件、调用代码解释器。包名是 agent-sandbox，导入 agent_sandbox。Container-Side HTTP Server API Reference容器内 HTTP Server（agent_sandbox.server）的完整 API 参考文档。Decision: agent_sandbox.server — User Opt-in In-Container HTTP Server ModuleStatus: implementedDecision: Authentication ModuleStatus: implementedDecision: Capability Model — Rejected AlternativesStatus: rejectedDecision: Change envd_inject default from True to FalseStatus: implementedDecision: CLI template profile, server stays provider-freeStatus: proposedDecision: Cloud end-to-end test infrastructureStatus: implementedDecision: Command Capability Model (Vocabulary + Default Baseline + Gating)Status: implementedDecision: Commands Module (L4)Status: implementedDecision: Connect Streaming Frame ParserStatus: implementedDecision: Custom Commands Schema for TemplatesStatus: implementedDecision: Data Models and Error HierarchyStatus: implementedDecision: Discovery API two-layer model (local static + remote authenticated)Status: proposedDecision: Docs ownership audit — the python-sdk repository documents only the SDKStatus: implementedDecision: Document the template server HTTP APIStatus: proposedDecision: Documentation completeness for CLI and Python SDK user guidesStatus: proposedDecision: Dual Authentication Mode (API Key + AK/SK)Status: implementedDecision: E2B Compatibility LayerStatus: implementedDecision: envd Two-Layer Container Service Model (Image-Baked envd/Gateway + User Opt-in Server Module)Status: implementedDecision: Files Module (L4)Status: implementedDecision: Filesystem Protocol (L2, Connect)Status: implementedDecision: Full expansion of Server module capabilities (6 → 42 endpoints, 8 capability groups)Status: implementedDecision: Hosted Agents slice — Codex and Qwen CodeStatus: proposedDecision: HTTP Transport LayerStatus: implementedDecision: Implement AK/SK → API Key token exchange (experimental)Status: implementedDecision: L3→L2 layer-violation fix and error-code reassignmentStatus: implementedDecision: Layered Configuration LoadingStatus: implementedDecision: Local Docker build and ACR push capabilityStatus: implementedDecision: Maintainer product decisions of 2026-10-12Status: implementedDecision: Make name positional-only in sandbox.custom() and run_command()Status: implementedDecision: No Backward Compatibility for the Capability ModelStatus: implementedDecision: one endpoint table, one policy engine, one dispatch pipelineStatus: implementedDecision: Open-source hygiene sweep and check-no-local-paths guardStatus: implementedDecision: Platform API Protocol (L2)Status: implementedDecision: Process Protocol (L2, Connect)Status: implementedDecision: PTY Terminal Protocol (L2, WebSocket)Status: implementedDecision: PyPI packaging decisions and pre-release P0 checklistStatus: supersededDecision: Real-cloud E2E suite and Definition of DoneStatus: implementedDecision: Release / Publish Flow for TemplatesStatus: proposedDecision: Remove all Serverless Sandbox → Agent Sandbox rename noticesStatus: implementedDecision: Restore Fail-Closed Capability Gate for CodeContextModule OnlyStatus: implementedDecision: Sandbox High-Level API (L4)Status: implementedDecision: SDK Capability Surface (Capability-Driven, Type-Safe Dynamic)Status: implementedDecision: Self-implement E2B Protocol Instead of Wrapping SDKStatus: implementedDecision: Server CommandRegistry standalone command registryStatus: implementedDecision: Server SDK 42-endpoint capability audit and retention decisionStatus: implementedDecision: Server SDK v2 guards package (path and command guards callable from the policy engine)Status: proposedDecision: Session Pluggable Storage BackendStatus: implementedDecision: Snapshot/Hibernate/Persistent Sandbox Deferred to FutureStatus: implementedDecision: Two-repository split (python-sdk + cli) and repository layoutStatus: proposedDecision: Use generation=1 (rund) for production; generation=2 has stdout bugStatus: implementedDecision: WebSocket TransportStatus: implementedDefinition of DoneThis is the binding product-owner rule for this repository. It is not an ADR (it has no Status); itE2B 云沙箱现状分析与痛点文档版本：v1.0 | 最后更新：2026-09-01E2B 兼容性本文档说明 Agent Sandbox 与 E2B Python SDK 的关系：哪些方法的形状一致、哪里不同、为什么。Agent Sandbox 不是 E2B 的直接替代品，它是另一套服务，只是方法名参考了 E2B，…E2B-style and Modal-style DemosClient SDK. These scripts run on your machine and call Sandbox or @sandbox.E2E 套件记录的已知问题套件把发现的每个产品缺陷固定为严格 xfail(@pytest.mark.known_issue)。缺陷修复后该测试会变为 XPASS 并使运行失败FC Agent Sandbox 官方文档技术提取报告日期: 2026-09-04FC Claude Code 镜像实地检查⚠️ HISTORICAL SNAPSHOT — 标注追加于 2026-09-24（任务 #122，承接 #109 审计；正文未改写）Fixture: this directory is an offline exa…Fixture: this directory is an offline example in the SDK repository, not theFull Suite Verification — 2026-09-04⚠️ HISTORICAL SNAPSHOT — annotation added 2026-09-24 (task #122, following the #109 audit)Hosted agents (Codex and Qwen Code)Client SDK. hosted_codex.py, hosted_qwen.py, complete_case.py, and local_files_and_session.py run on your mac…Local server HTTP end-to-end teststest_server_http_e2e.py starts a real python -m agent_sandbox.server serve subprocess onMCP Server 设计Agent Sandbox MCP Server 将沙箱能力暴露为 MCP (Model Context Protocol) Tools，让 AI Agent（Cursor、Claude Desktop、VS Code…MCP 集成Agent Sandbox 提供 MCP（Model Context Protocol）Server，使 AI IDE 和工具能够直接操作沙箱。Modal.com 设计模式深度分析文档版本：v1.0 | 最后更新：2026-09-01Module Specifications & Architecture DecisionsThis directory contains Architecture Decision Records (ADRs) and module specificationsOpenSandbox live-test helpersThis directory is tier T4 of the provider end-to-end plan (中文). T0–T3 do not need this server. T5 is the Alib…OpenSandbox 作为 Agent Sandbox 提供方：调研、API 映射、配置项与测试计划状态：评审记录，不是现行规范OpenSandbox 提供方：对抗式端到端记录状态：归档。不是现行规范。Point-in-time artifacts that back decisio…Point-in-time artifacts that back decisions in ../notes/. They are kept verbatim and are notPyPI 发布就绪审计报告（Serverless Sandbox SDK + sbox CLI）⚠️ SUPERSEDED / 历史快照（HISTORICAL SNAPSHOT） — 标注追加于 2026-09-24（任务 #122，承接 #109 审计；正文未改写）Python Hello 模板Server SDK。 commands.py 在沙箱里面启动。call_api.py 是 Client SDK：在外面调用已经起来的服务。Quickstart DemosClient SDK. These scripts run on your machine. They create a sandbox and use it. The service inside the image…Reference providersProvider plugins used by the test-suite and as templates for plugin authors.Repository Layout Review: python-sdk and cliStatus: recommendation (architecture review, 2026-10-12) - written read-only against theSDK API 设计agent-sandbox 包是运行时客户端：创建沙箱、使用沙箱、销毁沙箱。它提供两种写法（命令式和声明式）。模板的构建与部署归 abx CLI，运行 Agent 归 Agents API。SDK 使用指南本文详述 Agent Sandbox Python SDK 的完整使用方法。Server Framework Refactoring — Full Test Suite Verification⚠️ HISTORICAL SNAPSHOT — annotation added 2026-09-24 (task #122, following the #109 audit)Server HTTP API 参考沙箱内服务端（agent_sandbox.server，端口 9000；PTY WebSocket 在 9001）的线上契约。逐路由的行为见模板服务器 HTTP API。Agents 路由见 Agents API 参考…Server SDKServer SDK 跑在沙箱里面。它是镜像启动后一直听着的 HTTP 服务，默认端口 9000。包名是 agent-sandbox-server，导入 agent_sandbox.server。模板的 command…Server SDKServer SDK. This package runs inside a sandbox image. It is the HTTP service the image starts (default port 9…Server SDK v2：目标设计与实现状态状态：归档。不是现行规范。Template Fixtures（离线测试夹具）Server SDK。 每个模板里的 commands.py 随镜像启动，在沙箱里面听 HTTP。python-hello/call_api.py 是例外：它跑在沙箱外面，对已经在听的服务发请求，属于 Client S…template.yaml 规范本文档精确定义 template.yaml 文件的所有字段（使用者视角）。This repository is a Python library and a…This repository is a Python library and an in-sandbox HTTP service. It has no graphical application. Text, JS…Verification: client SDK local HTTP end-to-end (2026-10-12)Subprocess python -m agent_sandbox.server serve on 127.0.0.1 (ephemeral port, --base-dir under the test temp…Verification: cloud examples on alicloud-express (2026-10-13)Real Sandbox.create runs of the Python SDK examples that had not been executed against the cloud. Provider is…Verification: local server HTTP end-to-end (2026-10-12)Subprocess python -m agent_sandbox.server serve on 127.0.0.1 (ephemeral port). Checks are a separate HTTP cli…Verification: real-cloud E2E suite foundation (python-sdk)Date: 2026-10-12Verification: SDK defects KI-001 to KI-007 and KI-010 fixed (python-sdk client-sdk)Date: 2026-10-12Verification: small-image ACR push and base sandbox create (2026-10-13)Follow-up to KI-011 (full image push too slow from this host). One tiny local image, one short ACR push, and…Wave 3 全量验证报告⚠️ HISTORICAL SNAPSHOT / 历史验证快照 — 标注追加于 2026-09-24（任务 #122，承接 #109 审计）与其他沙箱工具的对比本文档客观对比 Agent Sandbox (abx) 与其他主流沙箱及远程执行平台：E2B、Modal、Docker Sandbox。云上端到端练习在默认提供方 阿里云极速版（alicloud-express）上，用真实沙箱把仓库里的云端示例跑一遍。不需要把镜像推到 ACR。云沙箱用户场景全景调研文档版本：v1.0 | 最后更新：2026-09-01云沙箱竞品深度对比文档版本：v1.0 | 最后更新：2026-09-01云沙箱调研文档索引最后更新：2026-09-01从 E2B 迁移Agent Sandbox 沿用 E2B 风格的方法名，所以大多数 E2B 调用点只需改 import 就能迁移。它不是即插即用的替代品：线协议、凭证和一些行为都不同。本页列出需要改动的地方。会话持久化会话（Session）将沙箱与一个人类可读名称关联，方便在不同终端或时间点反复连接同一个沙箱。命令与 SDK 对照同一行是同一件事在三家产品里的最近入口。它不是参数级兼容，也不是把 Agent Sandbox 收成其中一家的子集。场景：创建、执行、读取、销毁Client SDK。 这个脚本跑在你的机器上。它在本地拉起一个 Server SDK 进程，只是为了让客户端有服务可调。声明式用法（@sandbox 装饰器）@sandbox 装饰器让你以声明式方式在远程沙箱中执行 Python 函数，无需手动管理沙箱生命周期。官方基础镜像与 Server SDK状态：v2（已评审，见 fine-grained-capabilities-review.md），与细粒度能力设计一起评审：客户端 / 服务端对齐：差距矩阵状态：v2（已评审，见 fine-grained-capabilities-review.md）。对 agent-sandbox-server 的每一条路由与 agent-sandbox（api/、protocol/）容器内服务边界 (envd) 与"注册式自定义命令"可行性研究⚠️ SUPERSEDED / 历史快照（HISTORICAL SNAPSHOT） — 标注追加于 2026-09-24（任务 #122，承接 #109 审计；正文未改写）常见问题（FAQ）1. 检查网络：确认可以访问 api.cn-hangzhou.e2b.fc.aliyuncs.com快速入门这是 Client SDK：在你的机器上安装、创建并使用沙箱。要写进镜像、在沙箱里启动的服务见 Server SDK。托管代理用户向的说明和一条能跑完的案例在 Agents API。本页是路由参考。提供方与凭证 —— 命名方案与提供方插件架构状态：已接受（经两轮对抗式评审，见 providers-and-credentials-review.md） · 范围：Python SDK（client-sdk）与 Node.js abx CLI · 面向 CLI…提供方与凭证 —— 对抗式评审记录状态：归档。不是现行规范。提供方编写体验评估 —— 接入一个新提供方有多难？状态：评估（基于证据），已应用一轮修复（见第 10 节） · 对象：opensandbox exec 提供方插件（awesome-providers/opensandbox）。插件源码在该目录，不在本仓库。评估依据 S…提供方（Providers）提供方就是一个沙箱后端。Agent Sandbox 自带一个内置提供方，并且可以从插件加载更多提供方。整体架构评审：过度设计、重复与体验矛盾评审日期：2026-10-13。范围：cli（@agent-sandbox/cli，命令 abx）和 python-sdk（agent-sandbox、agent-sandbox-server）。文件与命令控制模板如何限制沙箱服务器可以触及的路径和程序。如何打开策略、选择器，以及全部端点 id，见 细粒度能力。这些路由的 HTTP 形状见模板服务器 HTTP API。template.yaml 的 server: 块见 te…最佳实践如何运行沙箱内的服务器。路由形状见模板服务器 HTTP API。路径和命令限制见文件与命令控制。构建与部署Python SDK（agent-sandbox）是运行时客户端：创建、使用、销毁沙箱。它不构建镜像，也不注册模板。模板的构建和部署由 abx CLI 负责。架构概览本文档简述 Agent Sandbox 的整体架构，帮助理解 SDK、CLI、Server 之间的关系。模板体系设计模板（Template）是 Agent Sandbox 的运行环境蓝图，定义了沙箱的基础镜像、预装软件、默认配置和启动行为。模板体系分为官方核心模板、社区模板和自定义模板三个层次。模板的核心分发机制基于 GitHub…模板服务器 HTTP API生成的模板包含 Dockerfile、commands.py 和 template.yaml。沙箱启动后，调用方通过 HTTP 访问它。commands.py 是容器的主进程：它用 @command 注册命名命令，并调…沙箱环境变量指南本指南说明环境变量在 Agent Sandbox 中的工作方式，涵盖两种独立的进程作用域、注入方法、直接执行（direct-exec）语义以及推荐实践。沙箱生命周期本文档解释沙箱的完整生命周期、状态转换和超时机制。沙箱类型体系设计Agent Sandbox 提供三种沙箱模式，覆盖从一次性脚本到长期运行服务的全部场景。当前仅临时沙箱（Ephemeral）完整支持，持久沙箱和休眠沙箱为远期规划。测试与完成定义Python SDK(agent-sandbox)与沙箱内服务(agent-sandbox-server)如何做端到端验证,以及判定一项变更"算完成"的规则。真实云端 E2E 套件(Python SDK)针对真实阿里云 FC 智能体沙箱平台对 agent-sandbox(client-sdk)与 agent-sandbox-server(server-sdk)做端到端测试:系统架构设计 — 五层分层架构Agent Sandbox SDK 采用五层分层架构，从底层传输到上层 AI 集成逐层抽象，每层职责单一、边界清晰，用户可在任意层级接入使用。SDK 零 LLM 依赖，不依赖 E2B SDK，直接对接 envd 数据面…细粒度能力每条路由只有一个端点 id，每个端点一条规则，决定它能不能被调用，以及路径、命令、大小和频率限制。规则前面没有第二道门。agents-cli 只放开会话相关的几条 Agents 路由，POST /shell 和 POS…细粒度能力、路径范围与权限状态：v2（已评审）。v1 草案经过 fine-grained-capabilities-review.md编写模板这是 Server SDK：commands.py 随镜像启动，在沙箱里面提供 HTTP 服务。在你的机器上创建并调用沙箱见 Client SDK。认证详解Agent Sandbox 支持两种认证模式：API Key 和 AK/SK（阿里云 AccessKey）。评审记录：细粒度能力、客户端/服务端对齐、基础镜像状态：归档。不是现行规范。配置参考本文档列出 Agent Sandbox 的所有配置项、环境变量、默认值和优先级规则。错误码参考所有 SDK 错误都继承自 SandboxError，携带 code（错误码）、message（消息）、suggestion（建议）、docs_url（文档 URL）属性。阿里云 FC 沙箱真实 E2E 验证⚠️ HISTORICAL SNAPSHOT / 历史验证快照 — 标注追加于 2026-09-24（任务 #122，承接 #109 审计）
Node.js SDK
模板
2026-10-14 对抗结论四份审查对着同一套代码。结论是：provider 先不要从 SDK 里搬走；OpenCode、Amp、Droid 保持 experimental。A minimal Python development environment…A minimal Python development environment template.Agents API for Codex and Qwen CodeAgents API for Codex and Qwen Code. The image does not preinstall either CLI.Awesome Templates for Agent SandboxA curated collection of sandbox templates for theclaude-code 是 Anthropic Claude Code 的沙箱模板claude-code 是 Anthropic Claude Code 的沙箱模板。镜像基于 python:3.12-slim，预装 Node.js 22、Python 3.12（虚拟环境在 /opt/venv）、np…codex 是 OpenAI Codex CLI 的沙箱模板codex 是 OpenAI Codex CLI 的沙箱模板。镜像基于 python:3.12-slim，预装 Python 3（/opt/venv）、Node.js 22、npm 包 @openai/codex，以及…Contributing to Awesome Templates for Agent SandboxThanks for adding a template. This repository is the catalog for the abxgemini 是 Gemini CLI 的沙箱模板gemini 是 Gemini CLI 的沙箱模板，状态是 experimental。镜像基于 python:3.12-slim，预装 Node.js 22 和 @google/gemini-cli@0.64.0。入口…gemini 镜像构建记录（2026-10-14）docker build -t abx-gemini:local gemini/ 退出码 0。镜像 id 979bcdd2f13b。Node.js 20 web service sandbox environmentNode.js 20 web service sandbox environment, suited for rapid development and deployment with Express, Fastify…openclaw 是 OpenClaw 开源 AI 编程 Agent 的沙箱模板openclaw 是 OpenClaw 开源 AI 编程 Agent 的沙箱模板，提供网关运行时。镜像基于 python:3.12-slim，预装 Node.js 22 和 npm 包 openclaw。系统工具有 g…qwen-code 是通义千问编码 Agent 的沙箱模板qwen-code 是通义千问编码 Agent 的沙箱模板，用 qwen-code CLI 做自然语言部署。镜像基于 python:3.12-slim，预装 Python 3.12（/opt/venv）、Node.js…Sandbox environment with Playwright + Chr…Sandbox environment with Playwright + Chromium preinstalled, suited for web scraping, UI automation testing,…Sandbox runtime for a DeepSeek model-driv…Sandbox runtime for a DeepSeek model-driven AI coding agent, supporting code generation, completion, and inte…Sandbox runtime for AI agents driven by N…Sandbox runtime for AI agents driven by NousResearch Hermes models, supporting tool calling and multimodal ta…Sandbox runtime for Anthropic Claude CodeSandbox runtime for Anthropic Claude Code, preinstalled with the Claude Code CLI to support AI-driven coding,…Sandbox runtime for the OpenAI Codex CLI…Sandbox runtime for the OpenAI Codex CLI agent, supporting AI-driven code generation and execution.Sandbox runtime for the OpenClaw open-sou…Sandbox runtime for the OpenClaw open-source AI coding agent, providing agent gateway and runtime support.Sandbox runtime for the Qoder AI coding a…Sandbox runtime for the Qoder AI coding assistant — an intelligent development sandbox combining Python 3.12…Sandbox runtime for the Qwen coding agent…Sandbox runtime for the Qwen coding agent — supports qwen-code-driven autonomous deployment and provides a Py…Self-hosted OpenAI Agents API compatible…Self-hosted OpenAI Agents API compatible service powered by Codex CLI.模板开发、上架与验收一份模板要进 awesome-templates.yaml 并且 status: official，必须同时满足下面的开发、上架和验收条件。只写 README、或者命令没有真正调用上游 CLI，不能上架。这批不做下面这些先不要在 awesome-templates 里建目录。验收要求是：一个目录、一份 python:3.12-slim 的 Dockerfile、commands.py 里的 @command 真正去调上游 CL…这是 Factory Droid 编码 CLI 的 Agent Sandbox 模板这是 Factory Droid 编码 CLI 的 Agent Sandbox 模板。镜像里预装官方 npm 包 @factory/cli@0.241.1（命令名 droid），版本与官方安装脚本 https://ap…这是 Gemini CLI 的 Agent Sandbox 模板这是 Gemini CLI 的 Agent Sandbox 模板。镜像基于 python:3.12-slim，安装 Node.js 22，再全局安装 npm 包 @google/gemini-cli@0.64.0（20…这是 OpenCode 编程 Agent 的 Agent Sandbox 模板这是 OpenCode 编程 Agent 的 Agent Sandbox 模板。镜像基于 python:3.12-slim，用 NodeSource 的 setup_22.x 安装 Node.js 22，再全局安装 n…这是 Sourcegraph Amp 编码 CLI 的 Agent Sandbox…这是 Sourcegraph Amp 编码 CLI 的 Agent Sandbox 模板。镜像基于 python:3.12-slim，用 Server SDK（agent_sandbox.server）在 9000 端…
Provider
Agent Sandbox providername: agent-sandbox-providerAwesome Providers for Agent SandboxA catalog of installable sandbox provider plugins for theCode of ConductThis project follows the Contributor Covenant, version 2.1. Report unacceptable behavior through the same con…Do not open a public issue for a vulnerab…Do not open a public issue for a vulnerability that exposes credentials, sandbox breakout, or installer trust…opensandbox 提供方插件一个 EPP/1 exec 提供方插件，让 Agent Sandbox 在Providers in this repository are installa…Providers in this repository are installable backends for the Agent Sandbox CLI and Python SDK. One directory…端到端测试方案本目录里的每个 provider 都用同一套分级。跑不了的层级记为 skip 并写明原因，不算通过。编写一个 providerProvider 是可安装的沙箱后端。本仓库里一个目录就是一个 provider。Python SDK 和 abx CLI 不包含具体实现；它们把这里的目录安装到 ~/.abx/providers/<id>，再和它通信。