概述

E2B 是一个开源基础设施项目，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。该项目提供了 JavaScript SDK（Node.js）和 Python SDK 两套开发工具包，使开发者能够轻松启动和控制云端沙箱环境。资料来源：packages/python-sdk/README.md:1

E2B 的核心价值在于为 AI 应用提供了一个安全、可控的代码执行环境。当 AI 模型生成代码后，开发者可以通过 E2B 在隔离的沙箱中运行这些代码，而无需担心安全问题或资源污染。资料来源：packages/js-sdk/README.md:1

核心功能

安全沙箱环境

E2B 沙箱是基于 Docker 容器技术构建的安全隔离环境。每个沙箱都是完全独立的，拥有自己的文件系统、网络和进程空间。这种隔离确保了运行在沙箱中的代码不会影响主机系统或其他沙箱。资料来源：packages/js-sdk/src/sandbox/index.ts:1

沙箱支持以下关键安全特性：

资料来源：packages/js-sdk/src/sandbox/sandboxApi.ts:1

多语言 SDK 支持

E2B 提供了两个官方的 SDK 实现：

#### JavaScript SDK

JavaScript SDK 面向 Node.js 环境，支持 TypeScript 和 JavaScript。安装方式如下：

npm i e2b

该 SDK 提供了完整的沙箱控制能力，包括文件系统操作、命令执行、进程管理等。资料来源：packages/js-sdk/README.md:1

#### Python SDK

Python SDK 面向 Python 环境，支持 Python 3.x。安装方式如下：

pip install e2b

该 SDK 提供了与 JavaScript SDK 类似的功能，并针对 Python 生态进行了优化。资料来源：packages/python-sdk/README.md:1

模板系统

E2B 的模板系统允许开发者定义预配置的沙箱环境。模板本质上是一个 Dockerfile，包含了基础镜像、环境变量、依赖安装等配置。资料来源：packages/js-sdk/src/template/index.ts:1

模板支持多种基础镜像来源：

资料来源：packages/js-sdk/src/template/types.ts:1

模板构建过程会将所有指令转换为 Dockerfile 格式，包括 RUN、COPY、ENV 等指令。资料来源：packages/js-sdk/src/template/index.ts:1

命令执行系统

沙箱支持通过命令执行系统运行任意命令。每个命令执行后会返回标准输出、标准错误和退出码。资料来源：packages/js-sdk/src/sandbox/commands/commandHandle.ts:1

命令执行的核心特性包括：

interface CommandResult {
  stdout: string    // 标准输出
  stderr: string    // 标准错误
  exitCode: number  // 退出码，0 表示成功
  error?: string    // 错误信息
}

开发者可以通过 wait() 方法异步等待命令执行完成，如果命令以非零退出码结束，将抛出 CommandExitError 异常。资料来源：packages/js-sdk/src/sandbox/commands/commandHandle.ts:1

文件系统操作

E2B 提供了强大的文件系统操作能力，支持多种文件格式读取和写入。资料来源：packages/js-sdk/src/sandbox/filesystem/index.ts:1

#### 文件读取格式

资料来源：packages/js-sdk/src/volume/index.ts:1

#### 文件写入

文件写入支持 gzip 压缩传输，并可通过 use_octet_stream 参数选择使用 multipart/form-data 或 application/octet-stream 格式上传。资料来源：packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:1

就绪检查命令

模板系统支持设置启动命令和就绪检查命令。就绪检查确保沙箱中的服务完全启动后才标记为可用状态。资料来源：packages/python-sdk/e2b/template/main.py:1

E2B 提供了几个内置的就绪检查工具：

资料来源：packages/js-sdk/src/template/readycmd.ts:1

存储卷管理

E2B 支持持久化存储卷功能，允许沙箱挂载外部存储。这些存储卷可以在沙箱之间共享数据，或用于持久化存储重要数据。资料来源：packages/js-sdk/src/sandbox/sandboxApi.ts:1

存储卷挂载配置示例：

const sandbox = await Sandbox.create('template-name', {
  volumeMounts: {
    '/data': 'my-volume-name'
  }
})

资料来源：packages/js-sdk/src/sandbox/sandboxApi.ts:1

MCP 服务器集成

E2B 模板系统支持集成 MCP（Model Context Protocol）服务器，允许在沙箱中运行各种 MCP 服务。资料来源：packages/python-sdk/e2b/template/main.py:1

添加 MCP 服务器的示例：

template.add_mcp_server('exa')
template.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])

注意：使用 MCP 服务器需要基础镜像预装了 mcp-gateway。资料来源：packages/python-sdk/e2b/template/main.py:1

系统架构

整体架构

graph TD
    A[开发者应用] --> B[E2B SDK]
    B --> C[API Gateway]
    C --> D[Sandbox Manager]
    D --> E[Docker Container]
    E --> F[envd Agent]
    F --> G[文件系统]
    F --> H[网络栈]
    F --> I[进程管理]

SDK 分层架构

graph TD
    A[用户代码] --> B[高级 API]
    B --> C[连接配置]
    C --> D[API Client]
    D --> E[HTTP/REST]

API 客户端配置

E2B SDK 内部使用 HTTP 客户端与后端 API 通信，支持丰富的配置选项。资料来源：packages/python-sdk/e2b/api/client/client.py:1

资料来源：packages/python-sdk/e2b/api/client/client.py:1

命令行工具

E2B 提供了命令行工具用于管理模板。主要命令包括：

模板构建

e2b template build

该命令会根据指定目录下的 Dockerfile 或模板配置构建沙箱模板。资料来源：packages/cli/src/commands/template/build.ts:1

模板创建

e2b template create

该命令用于创建新的沙箱模板，支持交互式配置。资料来源：packages/cli/src/commands/template/create.ts:1

快速开始

1. 安装 SDK

根据使用的编程语言选择对应的 SDK 安装命令：

# JavaScript/TypeScript
npm i e2b

# Python
pip install e2b

2. 获取 API 密钥

1. 访问 e2b.dev 注册账号
2. 在仪表板获取 API 密钥
3. 设置环境变量

export E2B_API_KEY=e2b_***

3. 创建沙箱

JavaScript 示例：

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('python-default')
const result = await sandbox.commands.run('echo "Hello World"')
console.log(result.stdout)
await sandbox.close()

Python 示例：

import e2b

sandbox = e2b.Sandbox()
result = sandbox.commands.run('echo "Hello World"')
print(result.stdout)
sandbox.close()

环境变量配置

错误处理

E2B SDK 定义了多种错误类型用于处理不同的异常情况：

资料来源：packages/js-sdk/src/sandbox/commands/commandHandle.ts:1

相关资源

• 官方网站：https://www.e2b.dev/
• JavaScript SDK NPM：https://www.npmjs.com/package/e2b
• Python SDK PyPI：https://pypi.org/project/e2b/

概述

E2B 是一个开源基础设施平台，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。系统架构围绕三个核心概念构建：沙箱（Sandbox）、模板（Template） 和 API 客户端。这种设计使得开发者可以通过 SDK 定义可复现的运行时环境，并动态创建和管理隔离的执行实例。

资料来源：README.md:1-10

核心组件架构

E2B 系统由以下主要组件构成：

资料来源：packages/js-sdk/README.md:1-20

SDK 架构

SDK 导出结构

JavaScript SDK 和 Python SDK 都遵循统一的模块化设计，核心导出包括：

graph TD
    A[E2B SDK] --> B[Sandbox 类]
    A --> C[Template 类]
    A --> D[辅助函数]
    B --> B1[启动/停止沙箱]
    B --> B2[文件系统操作]
    B --> B3[进程管理]
    B --> B4[网络访问]
    C --> C1[基础镜像选择]
    C --> C2[依赖安装]
    C --> C3[环境变量配置]
    C --> C4[启动命令设置]

资料来源：packages/js-sdk/src/index.ts、packages/python-sdk/e2b/sandbox/main.py

API 客户端架构

SDK 通过统一的 API 客户端与后端服务通信：

资料来源：packages/js-sdk/src/api/metadata.ts:1-20

沙箱（Sandbox）架构

沙箱生命周期

stateDiagram-v2
    [*] --> 创建中: 调用 sandbox.start()
    创建中 --> 运行中: envd 服务就绪
    运行中 --> 暂停中: 调用 sandbox.pause()
    暂停中 --> 运行中: 调用 sandbox.resume()
    运行中 --> 停止中: 调用 sandbox.kill() 或超时
    停止中 --> [*]

资料来源：packages/js-sdk/src/sandbox/index.ts、packages/python-sdk/e2b/sandbox/main.py

沙箱创建请求

沙箱创建时，SDK 向后端发送包含完整配置的对象：

interface NewSandbox {
  templateID: string;           // 模板标识符
  metadata?: Record<string, unknown>;
  mcp?: Record<string, unknown>; // MCP 服务器配置
  envVars?: Record<string, string>;
  timeout?: number;              // 超时时间（秒）
  secure?: boolean;              // 安全模式
  allow_internet_access?: boolean;
  network?: NetworkConfig;
  autoPause?: boolean;
  autoResume?: { enabled: boolean };
  volumeMounts?: VolumeMount[];
}

资料来源：packages/js-sdk/src/sandbox/sandboxApi.ts:1-30

沙箱文件系统

沙箱提供虚拟文件系统，支持以下操作：

资料来源：packages/js-sdk/src/sandbox/index.ts、packages/python-sdk/e2b/sandbox/main.py

模板（Template）架构

模板构建器模式

Template 使用流式构建器（Builder）模式，允许链式调用定义环境：

graph LR
    A[Template] --> B[基础镜像]
    B --> C[依赖安装]
    C --> D[环境变量]
    D --> E[启动命令]
    E --> F[TemplateFinal]

资料来源：packages/js-sdk/src/template/types.ts:1-50

模板配置选项

资料来源：packages/js-sdk/src/template/types.ts:50-150、packages/python-sdk/e2b/template/main.py:1-100

模板构建流程

graph TD
    A[定义 Template] --> B[调用 build 方法]
    B --> C[生成 Dockerfile]
    C --> D[上传到 E2B 构建服务]
    D --> E{构建状态}
    E -->|building| F[轮询构建状态]
    F --> E
    E -->|success| G[返回 BuildInfo]
    E -->|error| H[抛出 BuildError]

资料来源：packages/js-sdk/src/template/index.ts:1-80

启动就绪检查

系统支持多种就绪检查策略：

资料来源：packages/js-sdk/src/template/readycmd.ts:1-50

环境变量和配置

SDK 配置

资料来源：packages/js-sdk/src/api/metadata.ts:1-20

沙箱环境变量

沙箱创建时可传入环境变量，格式为键值对映射：

# Python SDK 示例
sandbox = Sandbox(
    template="my-template",
    envs={
        "NODE_ENV": "production",
        "DATABASE_URL": "postgres://..."
    }
)

// JavaScript SDK 示例
const sandbox = await Sandbox.create({
    template: "my-template",
    envs: {
        "NODE_ENV": "production",
        "DATABASE_URL": "postgres://..."
    }
})

资料来源：packages/js-sdk/src/sandbox/sandboxApi.ts:10-20

MCP 服务器集成

E2B 支持 MCP（Model Context Protocol）服务器集成，允许沙箱访问外部工具和服务：

graph LR
    A[MCP 服务器] -->|mcp-gateway| B[沙箱环境]
    B --> C[SDK 调用]
    C --> D[工具执行]

资料来源：packages/js-sdk/src/template/types.ts:100-130

部署架构

模板构建部署

graph LR
    A[本地开发] --> B[定义 Template]
    B --> C[Template.build]
    C --> D[E2B API]
    D --> E[Docker 构建]
    E --> F[镜像仓库]
    F --> G[生产环境]

资料来源：packages/cli/src/commands/template/build.ts:1-50

构建产物

安全模型

资料来源：packages/js-sdk/src/sandbox/sandboxApi.ts:15-25

依赖安装方法对比

资料来源：packages/js-sdk/src/template/types.ts:80-120、packages/python-sdk/e2b/template/main.py:50-150

总结

E2B 系统架构采用分层设计，通过统一的 SDK 抽象隐藏底层复杂性：

• 表现层：JavaScript SDK 和 Python SDK 提供统一的 API
• 通信层：API 客户端处理认证、请求序列化和错误处理
• 服务层：后端 API 和 envd 服务管理沙箱生命周期
• 执行层：Docker 容器提供资源隔离

这种架构使得开发者可以专注于业务逻辑，而无需关心底层基础设施的复杂性。

概述

E2B JavaScript/TypeScript SDK 是一个开源基础设施，允许用户在云端安全隔离的沙箱中运行 AI 生成的代码。该 SDK 提供了启动和控制沙箱的完整能力，支持 Node.js、Browser 和 Deno 运行时环境。

资料来源：packages/js-sdk/README.md

核心能力

资料来源：packages/js-sdk/package.json

架构设计

技术栈

graph TD
    A[JavaScript SDK] --> B[@connectrpc/connect-web]
    A --> C[@bufbuild/protobuf]
    A --> D[openapi-fetch]
    
    E[沙箱环境] --> F[envd 服务]
    F --> G[文件系统 API]
    F --> H[命令执行 API]
    F --> I[环境变量 API]
    
    B --> E
    C --> E
    D --> J[REST API]

依赖关系

SDK 核心依赖包括：

资料来源：packages/js-sdk/package.json:18-36

运行时支持

SDK 支持多种 JavaScript 运行时环境：

• Node.js: 主要支持版本 >=18
• Browser: 支持现代浏览器环境
• Deno: 原生支持 Deno 运行时

资料来源：packages/js-sdk/src/api/metadata.ts

安装与配置

安装方式

npm i e2b

环境变量配置

E2B_API_KEY=e2b_your_api_key_here

SDK 通过以下方式获取环境变量：

资料来源：packages/js-sdk/src/api/metadata.ts:17-29

export function getEnvVar(name: string) {
  if (runtime === 'deno') {
    return Deno.env.get(name)
  }

  if (typeof process === 'undefined') {
    return ''
  }

  return process.env[name]
}

默认请求头

SDK 自动附加以下元数据头：

资料来源：packages/js-sdk/src/api/metadata.ts:7-15

API 端点

沙箱管理接口

#### 创建沙箱

POST /sandboxes

请求体 schema 定义：

资料来源：packages/js-sdk/src/api/schema.gen.ts:18-35

interface paths {
    "/sandboxes": {
        post: {
            parameters: {
                query?: never;
                header?: never;
                path?: never;
                cookie?: never;
            };
            requestBody: {
                content: {
                    "application/json": components["schemas"]["NewSandbox"];
                };
            };
            responses: {
                201: {
                    headers: { [name: string]: unknown };
                    content: { "application/json": components["schemas"]["Sandbox"] };
                };
            };
        };
    };
}

#### 获取沙箱列表

GET /sandboxes

响应示例：

{
  "application/json": components["schemas"]["ListedSandbox"][]
}

资料来源：packages/js-sdk/src/api/schema.gen.ts:1-25

环境变量接口

#### 获取环境变量

GET /envs

响应结构：

interface paths {
    "/envs": {
        get: {
            parameters: {
                query?: never;
                header?: never;
                path?: never;
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                200: {
                    headers: { [name: string]: unknown };
                    content: {
                        "application/json": components["schemas"]["EnvVars"];
                    };
                };
            };
        };
    };
}

资料来源：packages/js-sdk/src/envd/schema.gen.ts:1-35

文件操作接口

#### 下载文件

GET /files

资料来源：packages/js-sdk/src/envd/schema.gen.ts:50-65

MCP 服务器支持

SDK 提供完整的 Model Context Protocol (MCP) 服务器类型定义。

支持的 MCP 服务器类型

资料来源：packages/js-sdk/src/sandbox/mcp.d.ts

MCP 服务器接口定义

export interface McpServer {
  airtable?: AirtableMCPServer;
  aks?: AzureKubernetesServiceAKS;
  apiGateway?: ApiGateway;
  apify?: ApifyMCPServer;
  arxiv?: ArXivMCPServer;
  astGrep?: AstGrep;
  // ... 更多服务器类型
}

模板系统

模板类型定义

资料来源：packages/js-sdk/src/template/types.ts

SDK 提供链式 API 构建模板：

interface TemplateBuilder {
  // 包管理器安装
  npmInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;
  bunInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;
  yarnInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;
  pnpmInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;
  
  // 系统包安装
  aptInstall(packages: string | string[], options?: { noInstallRecommends?: boolean; fixMissing?: boolean }): TemplateBuilder;
  
  // MCP 服务器
  addMcpServer(servers: string | string[]): TemplateBuilder;
}

模板使用示例

// 使用基础镜像创建模板
const template = Template()
  .fromBaseImage()
  .runCmd('echo Hello World E2B!')

// 安装 npm 包
template.npmInstall('express')
template.npmInstall(['lodash', 'axios'])
template.npmInstall('typescript', { dev: true })

// 安装系统包
template.aptInstall('vim')
template.aptInstall(['git', 'curl'], { noInstallRecommends: true })

// 添加 MCP 服务器
template.addMcpServer('exa')
template.addMcpServer(['brave', 'github'])

快速开始

基本使用流程

graph LR
    A[初始化 SDK] --> B[创建沙箱]
    B --> C[执行命令/操作文件]
    C --> D[获取结果]
    D --> E[停止沙箱]

完整示例

资料来源：packages/js-sdk/README.md

import { Sandbox } from 'e2b'

// 创建沙箱实例
const sandbox = await Sandbox.create()

// 执行命令
const result = await sandbox.commands.run('echo "Hello from E2B!"')

// 读写文件
await sandbox.filesystem.write('/data/example.txt', 'Hello World')
const content = await sandbox.filesystem.read('/data/example.txt')

// 停止沙箱
await sandbox.close()

环境变量设置

// 设置 API 密钥
const E2B_API_KEY = process.env.E2B_API_KEY

构建配置

tsup 配置

资料来源：packages/js-sdk/tsup.config.js

export default defineConfig({
  minify: false,
  target: ['es2017'],
  sourcemap: true,
  dts: true,
  format: ['esm', 'cjs'],  // 同时支持 ESM 和 CommonJS
  clean: true,
  entry: {
    index: './src/index.ts',
  },
  esbuildOptions: (options) => {
    options.legalComments = 'none'
    return options
  },
})

输出格式

SDK 关键词

资料来源：packages/js-sdk/package.json:26-39

e2b, ai-agents, agents, ai, code-interpreter, sandbox, code, runtime, vm, nodejs, javascript, typescript

相关资源

概述

E2B Python SDK 是一个开源的基础设施库，用于在云端安全隔离的沙箱环境中运行 AI 生成的代码。该 SDK 提供了创建和控制沙箱的能力，支持同步和异步两种操作模式。开发者可以通过简单的 API 调用，在隔离环境中执行命令、运行代码，并与管理服务进行通信。

核心架构

模块结构

Python SDK 主要由以下几个核心模块组成：

运行时架构图

graph TD
    A[开发者应用] --> B[Python SDK]
    B --> C{同步/异步模式}
    C -->|同步| D[sandbox_sync]
    C -->|异步| E[sandbox_async]
    D --> F[API 客户端]
    E --> F
    F --> G[E2B API 服务]
    G --> H[沙箱实例]
    H --> I[envd 进程]
    I --> J[隔离文件系统]
    I --> K[网络环境]

沙箱管理

创建沙箱

Python SDK 提供了两种沙箱创建方式：同步和异步。

#### 异步创建方式

from e2b import Sandbox
import asyncio

async def main():
    sandbox = await Sandbox.create()
    # 执行操作
    await sandbox.close()

asyncio.run(main())

资料来源：packages/python-sdk/e2b/sandbox_async/main.py

#### 同步创建方式

from e2b import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.commands.run('echo "Hello from E2B!"')
    print(result.stdout)

资料来源：README.md

沙箱响应模型

沙箱创建成功后会返回 SandboxCreateResponse 对象，包含以下字段：

资料来源：packages/python-sdk/e2b/sandbox_async/sandbox_api.py

沙箱生命周期管理

stateDiagram-v2
    [*] --> 创建中: Sandbox.create()
    创建中 --> 运行中: 沙箱启动成功
    运行中 --> 停止中: sandbox.close()
    停止中 --> 已停止: 资源清理完成
    创建中 --> 失败: API 错误
    运行中 --> 失败: 连接断开
    失败 --> [*]
    已停止 --> [*]

模板系统

模板构建器

模板系统允许开发者定义沙箱的初始环境配置，包括基础镜像、系统包安装、环境变量设置等。

#### 基础镜像选择

from e2b import Template

template = (
    Template()
    .from_python_image('3')      # Python 3
    # 或
    .from_node_image('lts')      # Node.js LTS
    # 或
    .from_bun_image('latest')    # Bun 最新版
    # 或
    .from_base_image()           # E2B 默认基础镜像
)

资料来源：packages/python-sdk/e2b/template/main.py

#### 系统包安装

template = (
    Template()
    .from_ubuntu_image('24.04')
    .apt_install('vim')
    .apt_install(['git', 'curl', 'wget'])
)

#### 环境变量配置

template.set_envs({
    'NODE_ENV': 'production',
    'PORT': '8080'
})

启动命令配置

from e2b import Template, wait_for_url, wait_for_port, wait_for_file

template = (
    Template()
    .from_node_image()
    .copy('app.js', '/home/user/')
    .set_start_cmd('node app.js', wait_for_port(3000))
)

资料来源：packages/python-sdk/e2b/template/readycmd.py

模板构建

from e2b import Template

template = (
    Template()
    .from_python_image('3')
    .copy('requirements.txt', '/home/user/')
    .run_cmd('pip install -r /home/user/requirements.txt')
)

# 构建带标签的模板
Template.build(template, 'my-python-env:v1.0')

# 构建带多标签的模板
Template.build(template, 'my-python-env', tags=['v1.1.0', 'stable'])

资料来源：packages/python-sdk/e2b/template_sync/main.py

进程与命令执行

命令运行

在沙箱中执行命令有两种方式：

#### 使用 commands.run()

result = sandbox.commands.run('echo "Hello from E2B!"')
print(result.stdout)  # Hello from E2B!

#### 使用 process 模块

process = sandbox.process.start(
    cmd='python app.py',
    cwd='/home/user'
)

资料来源：packages/python-sdk/example.py

进程通信协议

进程通信使用 protobuf 定义的协议，核心模型包括：

资料来源：packages/python-sdk/e2b/envd/process/process_pb2.py

错误处理

异常类型

版本兼容性检查

SDK 会在创建沙箱时检查 envd 版本：

if Version(res.parsed.envd_version) < Version("0.1.0"):
    await SandboxApi._cls_kill(res.parsed.sandbox_id)
    raise TemplateException(
        "You need to update the template to use the new SDK. "
        "You can do this by running `e2b template build` in the directory with the template."
    )

资料来源：packages/python-sdk/e2b/sandbox_async/sandbox_api.py

安装与配置

环境要求

Python SDK 需要 Python 3.8 或更高版本。

安装命令

pip install e2b

环境变量配置

E2B_API_KEY=e2b_***

资料来源：packages/python-sdk/README.md

API 客户端配置

连接配置

from e2b import ConnectionConfig

config = ConnectionConfig(
    api_key="your-api-key",
    # 其他可选参数
)

API 客户端初始化

SDK 内部通过 get_api_client() 函数获取 API 客户端：

api_client = get_api_client(
    config,
    require_api_key=True,
    require_access_token=False,
)

资料来源：packages/python-sdk/e2b/template_async/main.py

快速开始示例

from e2b import Sandbox

# 同步使用
with Sandbox.create() as sandbox:
    result = sandbox.commands.run('echo "Hello from E2B!"')
    print(result.stdout)  # Hello from E2B!

# 异步使用
import asyncio
from e2b import Sandbox

async def main():
    sandbox = await Sandbox.create()
    result = await sandbox.commands.run('echo "Hello from E2B!"')
    print(result.stdout)
    await sandbox.close()

asyncio.run(main())

资料来源：README.md

进阶功能

MCP 服务器集成

模板支持添加 MCP (Model Context Protocol) 服务器：

template = (
    Template()
    .from_base_image()
    .add_mcp_server('exa')
    .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
)

资料来源：packages/python-sdk/e2b/template/main.py

缓存控制

跳过缓存，强制重新构建：

template.skip_cache().run_cmd('apt-get update')

Bun 包管理器

template = (
    Template()
    .from_bun_image()
    .bun_install('express')
    .bun_install(['lodash', 'axios'])
    .bun_install('tsx', g=True)  # 全局安装
)

数据模型

SandboxDetail

资料来源：packages/python-sdk/e2b/api/client/models/sandbox_detail.py

模板标签

@dataclass
class TemplateTag:
    tag: str           # 标签名称
    build_id: str      # 构建 ID
    created_at: datetime  # 创建时间

资料来源：packages/python-sdk/e2b/template_async/main.py

概述

E2B CLI 是一个命令行工具，用于构建和管理 E2B 云端沙箱以及沙箱模板。它提供了与 E2B 后端服务交互的便捷方式，使开发者能够通过终端快速创建、配置和部署沙箱环境。

CLI 工具是 E2B SDK 生态系统的重要组成部分，支持通过命令行直接操作沙箱和模板资源，而无需编写额外的代码。

资料来源：packages/cli/README.md:1-3

安装方式

E2B CLI 支持多种安装方式，开发者可以根据自己的环境选择最适合的方法。

通过 Homebrew 安装（macOS）

brew install e2b

通过 NPM 安装

npm install -g @e2b/cli

资料来源：packages/cli/README.md:10-19

认证配置

使用 CLI 之前需要进行身份认证。E2B 提供了交互式和非交互式两种认证方式。

交互式登录

e2b auth login

该命令会打开浏览器窗口引导用户完成认证流程。

非交互式认证

在没有浏览器访问权限的环境中，可以设置 E2B_ACCESS_TOKEN 环境变量进行认证。访问令牌可在 e2b.dev/dashboard 的账户设置中的团队选择器下获取。

E2B_ACCESS_TOKEN=sk_e2b_... e2b template build

[!IMPORTANT]

注意 E2B_ACCESS_TOKEN 与 E2B_API_KEY 的区别。CLI 使用访问令牌，而 SDK 使用 API 密钥。

资料来源：packages/cli/README.md:21-35

命令结构

CLI 采用分层命令结构，支持子命令扩展。命令文档生成工具可以将命令定义转换为 Markdown 格式的文档。

文档生成机制

CLI 提供了将命令自动转换为文档的功能，支持以下特性：

• 解析命令选项及其默认值
• 生成子命令文档
• 清理终端颜色代码
• 转义 HTML 特殊字符

// 处理子命令
command.commands.forEach((subcommand: any) => {
  const [, subMdContent] = commandToMd(subcommand, fullName)
  mdContent += subMdContent + '\n\n'
})

资料来源：packages/cli/src/utils/commands2md.ts:40-47

模板命令

模板是 E2B 沙箱的基础配置，定义了沙箱环境的初始状态。CLI 提供了完整的模板管理能力。

创建模板

创建新模板时，CLI 会生成相应的使用示例并支持多语言 SDK 代码片段输出。

e2b template create

模板创建完成后会输出成功信息，包含模板 ID 和使用示例：

✅ Building sandbox template {templateID} finished.

示例输出格式支持 Python SDK 和 JS SDK 两种格式，方便不同技术栈的开发者使用。

资料来源：packages/cli/src/commands/template/create.ts:1-15

构建模板

构建命令将本地模板配置打包并上传到 E2B 后端进行构建。

e2b template build

#### 构建流程状态

构建过程会返回不同的状态，CLI 根据状态码进行相应处理：

switch (template.status) {
  case 'building':
    // 继续轮询
    break
  case 'success':
    // 输出成功信息和示例
    console.log(`✅ Building sandbox template... finished.`)
    break
  case 'error':
    throw new Error(`❌ Building sandbox template... failed.`)
}

资料来源：packages/cli/src/commands/template/build.ts:50-80

#### Dockerfile 处理

CLI 支持自定义 Dockerfile 构建模板：

export function getDockerfile(root: string, file?: string) {
  // 检查用户指定的 Dockerfile 是否存在
  if (file) {
    const dockerfilePath = path.join(root, file)
    const dockerfileContent = loadFile(dockerfilePath)
    
    if (dockerfileContent === undefined) {
      throw new Error(`No ${dockerfileRelativePath} found in the root directory.`)
    }
    
    return { dockerfilePath, dockerfileContent, dockerfileRelativePath }
  }
}

资料来源：packages/cli/src/commands/template/build.ts:95-110

构建产物格式

成功构建后，CLI 会输出格式化的模板信息：

console.log(
  `\n✅ Building sandbox template ${asFormattedSandboxTemplate({
    templateID: templateName,
  })} finished.\n${exampleHeader}\n${exampleUsage}\n`
)

输出包含：

• 模板 ID/别名
• 使用示例代码
• Python SDK 示例
• JS SDK 示例

资料来源：packages/cli/src/commands/template/create.ts:8-13

环境变量

CLI 使用以下环境变量进行配置：

资料来源：packages/cli/README.md:31-34

错误处理

CLI 实现了统一的错误处理机制：

构建错误

case 'error':
  throw new Error(
    `\n❌ Building sandbox template ${asFormattedSandboxTemplate({
      aliases,
      ...template,
    })} failed.\nCheck the logs above for more details or contact us ${asPrimary(
      '(https://e2b.dev/docs/support)'
    )} to get help.\n`
  )

文件缺失错误

if (dockerfileContent === undefined) {
  throw new Error(
    `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`
  )
}

资料来源：packages/cli/src/commands/template/build.ts:68-76

相关资源

• 官方文档：https://e2b.dev/docs
• CLI 文档：https://e2b.dev/docs/cli
• 支持渠道：https://e2b.dev/docs/support

资料来源：packages/cli/README.md:36-37

概述

沙箱生命周期管理是 E2B 平台提供的核心功能，用于控制沙箱实例在超时、异常或资源管理场景下的行为方式。通过生命周期配置，用户可以定义沙箱在空闲超时后是被终止（kill）还是暂停（pause），以及是否支持自动恢复（auto_resume）功能。 资料来源：packages/python-sdk/e2b/sandbox_async/main.py:15-17

核心概念

生命周期状态

E2B 沙箱支持以下生命周期状态：

生命周期配置参数

interface LifecycleConfig {
  on_timeout: "kill" | "pause"    // 超时行为（默认: "kill"）
  auto_resume: boolean            // 是否支持自动恢复（默认: false，仅在 pause 模式下有效）
}

创建沙箱时的生命周期配置

TypeScript SDK

import Sandbox from 'e2b'

const sandbox = await Sandbox.create('my-template', {
  lifecycle: {
    on_timeout: "pause",
    auto_resume: true
  }
})

Python SDK (异步)

from e2b import Sandbox

sandbox = await Sandbox.create(
    template='my-template',
    lifecycle={"on_timeout": "pause", "auto_resume": True}
)

Python SDK (同步)

from e2b import Sandbox

sandbox = Sandbox.create(
    template='my-template',
    lifecycle={"on_timeout": "pause", "auto_resume": True}
)

生命周期状态流转

stateDiagram-v2
    [*] --> Creating: 创建沙箱
    Creating --> Running: 创建成功
    Creating --> [*]: 创建失败
    
    Running --> Idle: 空闲超时
    Idle --> Running: 恢复操作
    Idle --> Paused: 到达超时阈值
    
    Paused --> Running: auto_resume=true<br/>访问时自动恢复
    Paused --> Terminated: 手动终止
    
    Running --> Terminated: 手动终止<br/>on_timeout="kill"
    Terminated --> [*]
    
    note right of Paused: 仅当 lifecycle.on_timeout="pause" 时触发
    note right of Idle: 平台内部状态

自动暂停与恢复机制

工作原理

1. 自动暂停：当沙箱在配置的超时时间内没有活跃操作时，平台自动将沙箱状态从 Running 转换为 Paused，释放底层计算资源 资料来源：packages/python-sdk/e2b/sandbox_async/main.py:25

1. 自动恢复：当 auto_resume 设置为 true 时，对暂停状态沙箱的任何访问操作（如运行命令、读取文件）会自动触发沙箱恢复 资料来源：packages/python-sdk/e2b/sandbox_async/main.py:25

sequenceDiagram
    participant Client
    participant SandboxAPI
    participant SandboxInstance
    
    Client->>SandboxAPI: 创建沙箱 (lifecycle: auto_resume=true)
    SandboxAPI->>SandboxInstance: 启动沙箱
    
    Note over SandboxInstance: 空闲超时检测
    SandboxInstance-->>SandboxInstance: 自动暂停
    
    Client->>SandboxAPI: 访问暂停的沙箱
    SandboxAPI->>SandboxInstance: 自动恢复
    SandboxInstance-->>Client: 沙箱就绪
    
    Note over SandboxInstance: 恢复后继续使用

配置约束

CLI 沙箱信息查看

通过 E2B CLI 可以查看沙箱的生命周期状态：

e2b sandbox info <sandboxID>

返回的沙箱信息包含以下生命周期相关字段：

最佳实践

1. 开发调试场景

使用默认的 kill 模式，简化资源管理：

const sandbox = await Sandbox.create('debug-template', {
  lifecycle: {
    on_timeout: "kill"  // 默认值
  }
})

2. 长时任务场景

使用暂停模式配合自动恢复，避免重复创建开销：

const sandbox = await Sandbox.create('worker-template', {
  lifecycle: {
    on_timeout: "pause",
    auto_resume: true
  },
  timeoutMs: 30 * 60 * 1000  // 30分钟活跃超时
})

3. 成本敏感场景

使用 kill 模式确保资源及时释放：

sandbox = await Sandbox.create(
    template='batch-template',
    lifecycle={"on_timeout": "kill"}
)

相关源码

• JavaScript SDK: packages/js-sdk/src/sandbox/sandboxApi.ts - 沙箱 API 调用实现
• Python SDK: packages/python-sdk/e2b/sandbox/sandbox_api.py - 沙箱 API 封装
• Python API Client: packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py - 创建沙箱 API 请求
• 命令处理: packages/js-sdk/src/sandbox/commands/commandHandle.ts - 命令执行与生命周期交互
• Python 命令处理: packages/python-sdk/e2b/sandbox/commands/command_handle.py - Python 命令执行

文件系统操作

E2B 的文件系统操作模块提供了在沙箱（Sandbox）环境中读写文件和目录的完整能力。通过这个模块，用户可以在沙箱内执行文件浏览、读取、写入、监控等操作，是 E2B 沙箱与外部系统交互的核心途径之一。

概述

E2B 平台提供了在沙箱环境中执行 Git 操作和配置网络设置的完整功能。Git 操作主要通过模板构建器（Template Builder）在沙箱镜像构建阶段执行，支持克隆仓库、指定分支、浅克隆等常用功能。网络配置则允许用户在创建沙箱时控制网络访问权限和 MCP 网关的网络设置。

Git 操作

模板中的 Git 克隆

在 E2B 中，Git 操作主要通过 Template 类的 git_clone 方法实现。该方法在镜像构建阶段执行，而非沙箱运行时执行，这意味着所有 Git 相关的准备工作需要在构建模板时完成。

graph TD
    A[创建 Template 实例] --> B[选择基础镜像]
    B --> C[调用 git_clone 方法]
    C --> D[执行 git clone 命令]
    D --> E[构建并部署模板]
    E --> F[沙箱启动时已包含克隆的仓库]

Python SDK 中的 Git 操作

#### git_clone 方法签名

def git_clone(
    self,
    url: str,
    path: Optional[Union[str, Path]] = None,
    branch: Optional[str] = None,
    depth: Optional[int] = None,
    user: Optional[str] = None,
) -> "TemplateBuilder":

#### 参数说明

#### 使用示例

from e2b import Template

# 基本克隆
template = (
    Template()
    .from_python_image("3.11")
    .git_clone("https://github.com/user/repo.git", "/app/repo")
)

# 指定分支的浅克隆
template = (
    Template()
    .from_node_image("24")
    .git_clone(
        "https://github.com/user/repo.git",
        path="/workspace/project",
        branch="main",
        depth=1
    )
)

# 以 root 用户身份克隆
template = (
    Template()
    .from_base_image()
    .git_clone(
        "https://github.com/user/repo.git",
        "/root/repo",
        user="root"
    )
)

资料来源：packages/python-sdk/e2b/template/main.py:1-100

JavaScript SDK 中的 Git 操作

#### gitClone 方法签名

gitClone(
  url: string,
  path?: string,
  options?: {
    branch?: string;
    depth?: number;
  },
  user?: string
): TemplateBuilder

#### 使用示例

import { Template } from 'e2b'

// 基本克隆
const template = Template()
  .fromPythonImage('3')
  .gitClone('https://github.com/user/repo.git', '/app/repo')

// 指定分支和深度的克隆
const template = Template()
  .fromNodeImage('24')
  .gitClone(
    'https://github.com/user/repo.git',
    '/workspace/project',
    { branch: 'main', depth: 1 }
  )

git clone 命令生成

底层实现通过构建 git clone 命令行参数来实现功能：

args = ["git", "clone", url]
if branch:
    args.append(f"--branch {branch}")
    args.append("--single-branch")
if depth:
    args.append(f"--depth {depth}")
if path:
    args.append(str(path))

资料来源：packages/python-sdk/e2b/template/main.py:1-100

网络配置

沙箱网络访问控制

E2B 沙箱支持网络访问权限控制，用户可以在创建沙箱时通过 allow_internet_access 参数决定是否允许沙箱访问外部网络。

graph LR
    A[沙箱创建请求] --> B{allow_internet_access}
    B -->|True| C[允许访问外部网络]
    B -->|False| D[禁止访问外部网络]
    C --> E[可访问互联网资源]
    D --> F[仅限内部网络通信]

Python SDK 网络配置

#### 同步沙箱创建

with Sandbox.create(
    allow_internet_access=True,  # 允许网络访问
    network=True  # 启用网络功能
) as sandbox:
    result = sandbox.commands.run("curl https://api.example.com")

#### 异步沙箱创建

sandbox = await Sandbox.create(
    allow_internet_access=True,
    network=True,
    lifecycle=Lifecycle.KEEP_ALIVE
)

#### 网络参数说明

资料来源：packages/python-sdk/e2b/sandbox_sync/main.py:1-100

JavaScript SDK 网络配置

const sandbox = await Sandbox.create({
  allowInternetAccess: true,
  network: true,
})

MCP 网关网络配置

MCP 服务器添加

在 Python SDK 中，可以使用 add_mcp_server 方法为模板添加 MCP（Model Context Protocol）服务器。该功能要求基础镜像已预装 mcp-gateway。

def add_mcp_server(self, servers: Union[str, List[str]]) -> "TemplateBuilder":

#### 使用示例

template = (
    Template()
    .from_base_image()  # 需使用包含 mcp-gateway 的镜像
    .add_mcp_server('exa')
    .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
)

#### 前置条件检查

if self._template._base_template != "mcp-gateway":
    raise BuildException(
        "Devcontainers can only used in the devcontainer base template"
    )

资料来源：packages/python-sdk/e2b/template/main.py:1-100

MCP 网关启动配置

在沙箱运行时，MCP 网关通过特定命令启动，并使用环境变量进行认证配置：

token = str(uuid.uuid4())
sandbox._mcp_token = token

res = sandbox.commands.run(
    f"mcp-gateway --config {shlex.quote(json.dumps(mcp))}",
    user="root",
    envs={"GATEWAY_ACCESS_TOKEN": token},
)

资料来源：packages/python-sdk/e2b/sandbox_sync/main.py:1-100

环境变量配置

Git 操作环境配置

在执行 Git 操作时，可以通过 set_envs 方法设置环境变量：

template.set_envs({
    'GIT_TERMINAL_PROMPT': '0',  # 禁用 Git 交互提示
    'GIT_SSL_NO_VERIFY': 'true'   # 禁用 SSL 验证（测试环境）
})

#### set_envs 方法实现

instruction: Instruction = {
    "type": InstructionType.ENV,
    "args": [item for key, value in envs.items() for item in [key, value]],
    "force": self._template._force_next_layer,
    "forceUpload": None,
}
self._template._instructions.append(instruction)

资料来源：packages/python-sdk/e2b/template/main.py:1-100

缓存控制

跳过缓存构建

对于需要强制重新构建的指令，可以使用 skip_cache 方法：

template.skip_cache().run_cmd('apt-get update')

此方法会设置 _force_next_layer = True，确保后续指令及其所有层都重新构建，忽略任何缓存层。

资料来源：packages/python-sdk/e2b/template/main.py:1-100

完整使用示例

Python SDK 综合示例

from e2b import Template, Sandbox

# 创建包含 Git 仓库和 MCP 服务器的模板
template = (
    Template()
    .from_python_image("3.11")
    .git_clone(
        "https://github.com/user/private-repo.git",
        "/app/repo",
        branch="main",
        depth=1
    )
    .set_envs({
        "GIT_TERMINAL_PROMPT": "0",
        "APP_ENV": "production"
    })
    .run_cmd("pip install -r requirements.txt")
)

# 构建模板
build_info = template.build("my-app-template:v1.0")

# 使用模板创建沙箱并启用网络
with Sandbox.create(
    template=build_info.template_id,
    allow_internet_access=True,
    metadata={"user": "developer"}
) as sandbox:
    # 执行应用程序
    result = sandbox.commands.run("python /app/repo/main.py")
    print(result.stdout)

JavaScript SDK 综合示例

import { Template, Sandbox } from 'e2b'

// 创建模板
const template = Template()
  .fromNodeImage('24')
  .gitClone(
    'https://github.com/user/repo.git',
    '/workspace/project',
    { branch: 'main', depth: 1 }
  )
  .setEnvs({ NODE_ENV: 'production' })
  .runCmd('npm install')

// 构建并部署
const buildInfo = await Template.build(template, 'my-node-app:v1.0')

// 创建沙箱
const sandbox = await Sandbox.create({
  template: buildInfo.template.id,
  allowInternetAccess: true,
})

const result = await sandbox.commands.run('node /workspace/project/index.js')
console.log(result.stdout)

架构流程图

graph TD
    subgraph 模板构建阶段
        A[定义 Template] --> B[选择基础镜像]
        B --> C[执行 Git 克隆]
        C --> D[设置环境变量]
        D --> E[安装依赖]
        E --> F[构建 Docker 镜像]
        F --> G[部署到 E2B]
    end
    
    subgraph 沙箱运行阶段
        G --> H[创建沙箱实例]
        H --> I{allow_internet_access}
        I -->|True| J[启用网络访问]
        I -->|False| K[禁用网络访问]
        J --> L[运行用户代码]
        K --> L
        L --> M[执行命令]
        M --> N[访问网络资源]
    end
    
    subgraph MCP 网关配置
        O[配置 MCP 服务器]
        O --> P[启动 mcp-gateway]
        P --> Q[设置访问令牌]
        Q --> R[MCP 服务器就绪]
    end
    
    L -.-> R

注意事项

1. Git 凭证管理：对于私有仓库，需要在模板构建前配置适当的认证方式
2. 网络隔离：生产环境中应根据需求谨慎设置 allow_internet_access
3. 基础镜像要求：使用 MCP 功能需要选择包含 mcp-gateway 的基础镜像
4. 缓存策略：开发调试时可使用 skip_cache() 强制重新构建

概述

E2B 的模板系统是一套用于构建沙箱运行环境的配置框架，允许开发者通过声明式 API 定义沙箱的基础镜像、系统依赖、应用依赖、环境变量以及启动命令。该系统支持 JavaScript SDK 和 Python SDK，提供了统一且直观的接口来创建可复用的沙箱模板。

模板系统的核心是 TemplateBuilder 类，它采用链式调用模式（Builder Pattern），允许开发者通过 fluent API 逐步配置模板的各个组成部分。构建完成的模板可以通过 SDK 的 build 方法部署到 E2B 基础设施上，生成可供沙箱使用的镜像。

核心概念

模板状态机

模板在构建过程中经历以下状态转换：

stateDiagram-v2
    [*] --> TemplateBuilder: 初始化
    TemplateBuilder --> TemplateBuilder: 添加指令
    TemplateBuilder --> TemplateBuilder: 安装依赖
    TemplateBuilder --> TemplateFinal: set_start_cmd()
    TemplateFinal --> [*]: Template.build()
    
    state TemplateBuilder {
        [*] --> withInstructions
        withInstructions --> withInstructions
    }
    
    state TemplateFinal {
        [*] --> readyToBuild
    }

• TemplateBuilder：模板构建器状态，可以添加各种构建指令
• TemplateFinal：模板最终状态，仅在设置启动命令后达到，此时模板才能被构建

资料来源：packages/js-sdk/src/template/types.ts:50-55

基础镜像选择

E2B 支持多种基础镜像类型，通过不同的方法选择：

资料来源：packages/js-sdk/src/template/index.ts

JavaScript SDK 模板 API

安装包管理器

#### Bun 安装

// 安装单个包
template.bunInstall('express')

// 安装多个包
template.bunInstall(['lodash', 'axios'])

// 全局安装
template.bunInstall('typescript', { g: true })

// 安装为开发依赖
template.bunInstall('tsx', { dev: true })

// 从 package.json 安装
template.bunInstall()

资料来源：packages/js-sdk/src/template/types.ts:100-115

#### npm 安装

// 安装单个包
template.npmInstall('express')

// 安装多个包
template.npmInstall(['lodash', 'axios'])

// 全局安装
template.npmInstall('typescript', { g: true })

#### pip 安装

// 安装单个包
template.pipInstall('flask')

// 安装多个包
template.pipInstall(['flask', 'requests'])

// 安装 requirements.txt
template.pipInstall()

系统包安装

#### apt-get 安装

// 安装单个系统包
template.aptInstall('vim')

// 安装多个系统包
template.aptInstall(['git', 'curl', 'wget'])

// 不安装推荐包
template.aptInstall(['vim'], { noInstallRecommends: true })

// 修复缺失依赖
template.aptInstall(['vim'], { fixMissing: true })

资料来源：packages/js-sdk/src/template/types.ts:125-140

环境变量配置

// 设置环境变量
template.setEnvs({
  NODE_ENV: 'production',
  PORT: '8080',
  DATABASE_URL: 'postgres://localhost:5432/mydb'
})

环境变量通过 InstructionType.ENV 指令类型添加到指令列表中。

MCP 服务器集成

E2B 支持通过 mcp-gateway 集成 MCP (Model Context Protocol) 服务器：

// 添加单个 MCP 服务器
template.addMcpServer('exa')

// 添加多个 MCP 服务器
template.addMcpServer(['brave', 'firecrawl', 'duckduckgo'])

注意：使用 MCP 服务器功能需要基础镜像预装 mcp-gateway（如 mcp-gateway 镜像）。

资料来源：packages/js-sdk/src/template/types.ts:150-160

Devcontainer 支持

// 克隆仓库并启动 devcontainer
template
  .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
  .startDevcontainer('/my-devcontainer')

// 预构建并启动 devcontainer
template
  .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
  .betaDevContainerPrebuild('/my-devcontainer')
  .betaSetDevContainerStart('/my-devcontainer')

设置启动命令

// 使用字符串命令
template.setStartCmd(
  'python app.py',
  'curl -f http://localhost:3000/health'
)

// 使用 ReadyCmd 对象
template.setStartCmd(
  'python app.py',
  {
    cmd: 'curl -f http://localhost:3000/health',
    timeout: 30000
  }
)

setStartCmd 方法将模板状态从 TemplateBuilder 转换为 TemplateFinal，此时模板才能被构建。

Python SDK 模板 API

初始化与构建

from e2b import Template

template = (
    Template()
    .from_base_image()
    .run_cmd("echo Hello World E2B!")
)

# 构建模板
build_info = Template.build(template, "my-template:v1.0")

安装依赖

#### Bun 安装

# 安装单个包
template.bun_install('express')

# 安装多个包
template.bun_install(['lodash', 'axios'])

# 全局安装
template.bun_install('typescript', g=True)

# 开发依赖
template.bun_install('tsx', dev=True)

资料来源：packages/python-sdk/e2b/template/main.py:150-175

#### apt-get 安装

# 安装系统包
template.apt_install('vim')
template.apt_install(['git', 'curl', 'wget'])

# 不安装推荐包
template.apt_install('vim', no_install_recommends=True)

# 修复缺失依赖
template.apt_install('vim', fix_missing=True)

资料来源：packages/python-sdk/e2b/template/main.py:190-215

MCP 服务器

# 添加 MCP 服务器
template.add_mcp_server('exa')
template.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])

构建选项

JavaScript SDK

interface BuildOptions {
  // 镜像标签（可选）
  tags?: string[]
}

// 简单命名
await Template.build(template, 'my-template:v1.0')

// 多标签构建
await Template.build(template, 'my-template', { 
  tags: ['v1.0', 'stable', 'latest'] 
})

Python SDK

# 异步构建
import asyncio
from e2b import Template, AsyncTemplate

async def build_template():
    template = Template().from_base_image().run_cmd("echo test")
    build_info = await AsyncTemplate.build(template, "my-template:v1.0")

Docker 注册表配置

E2B 支持配置通用 Docker 注册表认证：

type GenericDockerRegistry = {
  type: 'registry'
  username: string
  password: string
}

此配置允许访问私有 Docker 镜像仓库。

CLI 命令行工具

E2B CLI 提供了模板构建的命令行接口：

# 构建模板
e2b template build

# 初始化新模板
e2b template init

CLI 使用 getDockerfile 函数获取 Dockerfile 内容：

export function getDockerfile(root: string, file?: string) {
  // 检查用户指定的 Dockerfile
  if (file) {
    const dockerfilePath = path.join(root, file)
    // ...
  }
  // 否则使用默认 Dockerfile
}

资料来源：packages/cli/src/commands/template/build.ts:55-80

模板构建流程

graph TD
    A[创建 Template] --> B[选择基础镜像]
    B --> C[安装系统包]
    C --> D[安装应用包]
    D --> E[设置环境变量]
    E --> F[配置 MCP 服务器]
    F --> G[设置启动命令]
    G --> H[调用 build 方法]
    H --> I[上传到 E2B 云端]
    I --> J[构建 Docker 镜像]
    J --> K[模板就绪]

缓存控制

模板系统支持选择性跳过缓存层：

// 跳过后续构建指令的缓存
template.skip_cache().runCmd('apt-get update')

这对于需要强制重新执行某些关键指令的场景非常有用。

错误处理

SDK 版本兼容性检查

if (compareVersions(res.data!.envdVersion, '0.1.0') < 0) {
  await this.kill(res.data!.sandboxID, opts)
  throw new TemplateError(
    'You need to update the template to use the new SDK.'
  )
}

CLI 构建错误

case 'error':
  throw new Error(
    `Building sandbox template failed.\n` +
    `Check the logs above for more details or contact us (https://e2b.dev/docs/support)`
  )

最佳实践

1. 使用特定版本标签：为模板指定明确的版本号，避免使用 latest 造成不一致
2. 合理拆分依赖：将系统依赖和应用依赖分开，便于缓存复用
3. 使用 skip_cache 策略：仅在必要时跳过缓存，减少构建时间
4. 健康检查命令：为 set_start_cmd 配置合理的 ready_cmd，确保沙箱真正就绪
5. 环境变量管理：使用环境变量而非硬编码配置值，提高模板可复用性

相关资源

• JavaScript SDK 文档
• Python SDK 文档
• CLI 工具文档

概述

E2B 的模板生成器（Template Generator）是 CLI 工具中负责将 Template 类实例转换为可部署模板的核心组件。它使用 Handlebars 模板引擎来生成各种格式的输出，包括 Dockerfile、启动脚本和使用示例代码。

模板生成器的主要职责包括：

• 将 TemplateClass 实例序列化为中间 JSON 格式
• 通过 Handlebars 模板引擎处理数据并生成最终输出
• 支持多种编程语言的代码示例生成（Python SDK、JS/TS SDK）
• 提供自定义 Handlebars helpers 用于模板逻辑处理

架构设计

组件关系

graph TD
    A[TemplateClass 实例] --> B[transformTemplateData]
    B --> C[TemplateJSON + HandlebarStep]
    C --> D[Handlebars 模板引擎]
    D --> E[最终输出]
    
    F[Handlebars 类] --> G[eq helper]
    F --> H[escapeQuotes helper]
    F --> I[escapeDoubleQuotes helper]
    
    J[模板类型] --> K[python-template.hbs]
    J --> L[typescript-template.hbs]
    J --> M[python-build-sync.hbs]

处理流程

sequenceDiagram
    participant CLI as CLI 命令
    participant TG as TemplateGenerator
    participant HB as Handlebars
    participant TPL as .hbs 模板文件
    
    CLI->>TG: 调用生成方法
    TG->>TG: transformTemplateData()
    TG->>TG: 解析 Template.toJSON()
    TG->>HB: 编译模板
    HB->>TPL: 读取 .hbs 文件
    TPL-->>HB: 模板内容
    HB-->>TG: 渲染结果
    TG-->>CLI: 返回生成的代码

Handlebars 核心实现

Handlebars 类

Handlebars 类是 Handlebars 库的封装，提供了模板编译和自定义 helpers 的支持。

文件位置: packages/cli/src/commands/template/generators/handlebars.ts

#### 类结构

class Handlebars {
  private handlebars: typeof HandlebarsLib

  constructor() {
    const handlebars = HandlebarsLib.create()
    handlebars.registerHelper('eq', function (a: any, b: any, options: any) {
      if (a === b) {
        return options.fn(this)
      }
      return ''
    })

    handlebars.registerHelper('escapeQuotes', function (str) {
      return str ? str.replace(/'/g, "\\'") : str
    })

    handlebars.registerHelper('escapeDoubleQuotes', function (str) {
      return str ? str.replace(/"/g, '\\"') : str
    })

    this.handlebars = handlebars
  }

  compile(template: string) {
    return this.handlebars.compile(template)
  }
}

资料来源：packages/cli/src/commands/template/generators/handlebars.ts:1-40

自定义 Helpers

模板系统提供了三个核心自定义 helpers：

#### eq Helper

用于在模板中进行条件渲染，类似于 Handlebars 内置的 if 但支持相等判断：

{{#eq instruction.type "RUN"}}
RUN {{instruction.args.[0]}}
{{/eq}}

#### escapeQuotes Helper

用于转义字符串中的单引号，防止在 JavaScript/TypeScript 代码中产生语法错误：

{{escapeQuotes command}}

#### escapeDoubleQuotes Helper

用于转义字符串中的双引号，防止在需要双引号包裹的上下文中产生语法错误：

{{escapeDoubleQuotes filename}}

数据转换层

transformTemplateData 函数

该函数负责将 TemplateClass 实例转换为 Handlebars 模板可用的数据格式。

签名:

export async function transformTemplateData(
  template: TemplateClass
): Promise<TemplateJSON & { steps: HandlebarStep[] }>

#### HandlebarStep 接口

interface HandlebarStep {
  type: string
  args?: string[]
  envVars?: Record<string, string>
  src?: string
  dest?: string
}

#### 转换过程

1. 调用 Template.toJSON(template, false) 获取 JSON 表示
2. 解析 JSON 为 TemplateWithStepsJSON 类型
3. 返回包含 steps 数组的合并结果

资料来源：packages/cli/src/commands/template/generators/handlebars.ts:59-74

模板类型

模板文件列表

E2B CLI 提供了多种预定义的 Handlebars 模板：

python-template.hbs

用于生成 Python SDK 的使用示例代码，包含：

• 模板初始化代码
• 环境变量设置
• 包安装指令
• 启动命令配置

typescript-template.hbs

用于生成 TypeScript/JavaScript SDK 的使用示例代码，包含：

• TypeScript 类型安全的模板构建
• 异步操作处理
• 错误处理模式

python-build-sync.hbs

用于生成同步构建相关的 Python 代码，支持：

• 同步模板构建流程
• 构建状态轮询
• 结果处理

模板指令类型

在 E2B 模板系统中，每条构建指令都被序列化为特定的数据结构：

指令类型枚举

指令数据结构

interface Instruction {
  type: InstructionType
  args: string[]
  force?: boolean
  forceUpload?: string | null
}

Dockerfile 生成

Template 类提供了 toDockerfile() 方法用于生成 Dockerfile 内容：

private toDockerfile(): string {
  let dockerfile = `FROM ${this.baseImage}\n`
  for (const instruction of this.instructions) {
    if (instruction.type === InstructionType.RUN) {
      dockerfile += `RUN ${instruction.args[0]}\n`
      continue
    }
    if (instruction.type === InstructionType.COPY) {
      dockerfile += `COPY ${instruction.args[0]} ${instruction.args[1]}\n`
      continue
    }
    if (instruction.type === InstructionType.ENV) {
      const values: string[] = []
      for (let i = 0; i < instruction.args.length; i += 2) {
        values.push(`${instruction.args[i]}=${instruction.args[i + 1]}`)
      }
      dockerfile += `ENV ${values.join(' ')}\n`
      continue
    }
    dockerfile += `${instruction.type} ${instruction.args.join(' ')}\n`
  }
  if (this.startCmd) {
    dockerfile += `ENTRYPOINT ${this.startCmd}\n`
  }
  return dockerfile
}

资料来源：packages/js-sdk/src/template/index.ts

使用示例

基础模板构建

from e2b import Template

template = (
    Template()
    .from_python_image("3.11")
    .pip_install("flask")
    .run_cmd("mkdir -p /app")
    .set_workdir("/app")
    .set_start_cmd("python app.py", "curl http://localhost:5000/health")
)

CLI 命令行使用

e2b template build --name my-template

生成的输出包含：

• ✅ 构建成功的确认消息
• Python SDK 使用示例
• JavaScript/TypeScript SDK 使用示例

资料来源：packages/cli/src/commands/template/create.ts

错误处理

模板生成过程中的错误处理机制：

if (dockerfileContent === undefined) {
  throw new Error(
    `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`
  )
}

资料来源：packages/cli/src/commands/template/build.ts

最佳实践

1. 模板命名规范

• 使用描述性名称：my-app-template
• 支持标签语法：my-app:v1.0

2. 指令顺序

推荐顺序：

1. from_image() 或其他基础镜像方法
2. set_envs() 环境变量设置
3. run_cmd() 系统命令
4. pip_install() / npm_install() 包安装
5. copy() 文件复制
6. set_workdir() 工作目录设置
7. set_start_cmd() 启动命令

3. 缓存优化

使用 skip_cache() 方法跳过特定指令的缓存：

template.skip_cache().run_cmd("apt-get update")

4. 环境变量转义

当在模板中使用特殊字符时，使用相应的转义 helpers：

{{escapeQuotes env_value}}

相关文档

• E2B Python SDK 文档
• E2B JS SDK 文档
• E2B CLI 文档
• 模板 API 类型定义

Pitfall Log / 踩坑日志

项目：e2b-dev/E2B

摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths。

1. 配置坑 · 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2b063fe8cb80490584e7647332a2c4c6 | https://github.com/e2b-dev/E2B/issues/1331 | 来源类型 github_issue 暴露的待验证使用条件。

2. 配置坑 · 来源证据：process was not killed when auto paused

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Closed Port Error

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。

6. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安装坑 · 来源证据：build status polling timed out

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。

8. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。

9. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8

• 严重度：medium
• 证据强度：source_linked
• 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment <details> <summary>The output of <code>python collect_env.py</code></summary> ``text Your output of python collect_env.py here ` </details> ### 🐛 Describe the bug run ` vllm serve google/gemma-3n-E2B-it -tp 1 `` on torch==2.8.0:…
• 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
• 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
• 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8

10. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.

11. 运行坑 · 来源证据：Support `AbortSignal` in JS SDK methods for request cancellation

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Support AbortSignal in JS SDK methods for request cancellation
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f74f7dd596784e88aff40ef33d5b505e | https://github.com/e2b-dev/E2B/issues/1312 | 来源类型 github_issue 暴露的待验证使用条件。

12. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。

13. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing

14. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium

15. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium

16. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：Docker Build Secrets Support

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

20. 安全/权限坑 · 来源证据：Template Build Fails with "syncing took too long" Error

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with "syncing took too long" Error
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

21. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown

22. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown