自定义沙箱快速入门

更新时间：2026-01-26

概览

本文将介绍如何使用sdk在沙箱服务创建自定义模版，以支持用户扩展沙箱功能。

说明：在构建自定义模版时沙箱服务会为用户的模版注入命令执行、文件操作的功能，用户无需在自己的模版内构建相关程序。

安装依赖

执行如下命令安装依赖

            Python
        
            JavaScript

1pip install e2b

1npm install e2b

指定镜像构建模版

基于ccr镜像仓库中的镜像构建模版，注意镜像仓库需要开通公网以及访问权限，否则沙箱服务无法拉取用户镜像

                Python
                
            

                from e2b import Template, wait_for_timeout
import os

os.environ["E2B_DOMAIN"] = "sandbox-execute.gz.baidubce.com"
# 修改为用户自己申请的api_key
os.environ["E2B_API_KEY"] = "bce-v3/****************************"

# 用户可替换自己的镜像仓库中的镜像
template = Template().from_image(
     image="ccr-******-pub.cnc.gz.baidubce.com/*******/ubuntu2204_python312:v1",
)

buildIf = Template.build_in_background(template,
                                        alias="test_custom_template", # 用户自定义模版id
                                        cpu_count=2,
                                        memory_mb=2048)
                                        
print(f"build_templateId: {buildIf.template_id}")
print(f"build_buildId: {buildIf.build_id}")
print(f"build_alias: {buildIf.alias}")
            

针对私有镜像，用户需要指定镜像仓库的账号密码，否则沙箱服务无法拉取用户镜像

                Python
                
            

                # 替换为用户镜像仓库的账号和密码
template = Template().from_image(
     image="ccr-*****-pub.cnc.bj.baidubce.com/******/sandbox:v1",
     username="******",
     password="*****"
)
            

基于模版构建新模版

用户在自己已有模版或者官方模版的基础上构建新模版，如下以基于官方模版browser-use为例

                Python
                
            

                template = Template().from_template(
     "browser-use-v1"   # 官方模版id/用户已有模版id
)

buildIf = Template.build_in_background(template,
                                        alias="browser_with_file_cmd", # 用户自定义模版id
                                        cpu_count=2,
                                        memory_mb=2048)

print(f"build_templateId: {buildIf.template_id}")
print(f"build_buildId: {buildIf.build_id}")
print(f"build_alias: {buildIf.alias}")
            

自定义模版会为用户注入文件操作和代码执行的功能，如上基于browser-use构建的自定义模版，除了操作浏览器外、也能直接向沙箱发起文件操作和命令执行。

基于命令构建模版

用户可以在指定模版基础镜像的基础上，添加dockerfile命令，如下基于browser-use官方模版的基础上添加用户'testuser'，并设置沙箱启动时用户为'testuser'

                Python
                
            

                template = Template().from_template(
     "browser-use-v1"
).run_cmd("useradd -m -s /bin/bash testuser").set_user("testuser")

buildIf = Template.build_in_background(template,
                                        alias="browser_with_file_cmd",
                                        cpu_count=2,
                                        memory_mb=2048)

print(f"build_templateId: {buildIf.template_id}")
print(f"build_buildId: {buildIf.build_id}")
print(f"build_alias: {buildIf.alias}")
            

Dockerfile指令和sdk命令映射关系

Dockerfile	Sdk
Run	run_cmd()
WORKDIR	et_workdir()
USER	set_user()
ENV	set_envs()
CMD / ENTRYPOINT	set_start_cmd()

当前暂不支持EXPOSE、VOLUME、COPY、ADD

查询模版列表、构建状态

后续用户可以在控制台查看自己的自定义模版和模版的构建状态，当前提供api的形式供用户临时查询模版和构建信息

工具类

                template_info_manager.py
                
            

                """
Template Information Manager

该工具类提供模版管理的高层接口，包括：
- 获取所有模版列表
- 根据模版名获取构建记录列表
- 获取指定构建记录
"""

import os
import requests
from typing import Any, Dict, List, Optional
from dataclasses import dataclass
from enum import Enum


class BuildStatus(str, Enum):
    """构建状态枚举"""
    BUILDING = "building"
    READY = "ready"
    ERROR = "error"


@dataclass
class TemplateInfo:
    """模版信息"""
    template_id: str
    template_name: str
    created_at: str
    public: Optional[bool] = None
    cpu_count: Optional[int] = None
    memory_mb: Optional[int] = None


@dataclass
class BuildInfo:
    """构建信息"""
    build_id: str
    template_id: str
    status: str
    cpu_count: Optional[int] = None
    memory_mb: Optional[int] = None
    errMsg: Optional[str] = None
    created_at: Optional[str]  = None
    finished_at: Optional[str] = None
    logs_count: Optional[int] = None


class TemplateInfoManager:
    """模版信息管理器"""

    def __init__(
            self,
            api_key: Optional[str] = None,
            domain: Optional[str] = None,
            debug: bool = False,
            timeout: int = 180
    ):
        """
        初始化管理器
        
        Args:
            api_key: API密钥，如果不提供则从环境变量E2B_API_KEY读取
            domain: 域名，如果不提供则从环境变量E2B_DOMAIN读取
            debug: 是否启用调试模式
            timeout: 请求超时时间（秒），默认180
        """
        self.api_key = api_key or os.environ.get("E2B_API_KEY")
        # 处理域名，确保不会是空字符串
        self.domain = domain or os.environ.get("E2B_DOMAIN")
        self.debug = debug
        self.timeout = timeout

        if not self.api_key:
            raise ValueError("API_KEY未设置")
        if not self.domain:
            raise ValueError("Domain未设置")
        # 构建API base URL
        self.api_url = f"https://api.{self.domain}"

        # 构建请求头
        self.headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json",
            "Accept": "application/json",
        }


    def list_templates(self) -> List[TemplateInfo]:
        """
        获取所有模版列表
        
        Args:
            team_id: 可选的团队ID
            
        Returns:
            模版信息列表
            
        Raises:
            Exception: 当API调用失败时
        """
        url = f"{self.api_url}/templates"
        params = {}

        try:
            response = requests.get(
                url,
                headers=self.headers,
                params=params,
                timeout=self.timeout
            )

            if response.status_code != 200:
                raise Exception(
                    f"HTTP {response.status_code}: {response.text}"
                )

            data = response.json()

            # 转换为TemplateInfo列表
            templates = []
            for item in data:
                # 使用.get()避免缺少字段的问题
                templates.append(TemplateInfo(
                    template_id=item.get("templateID", ""),
                    template_name=item.get("templateName", item.get("aliases", [""])[0] if item.get("aliases") else ""),
                    created_at=item.get("createdAt", ""),
                    public=item.get("public"),
                    cpu_count=item.get("cpuCount"),
                    memory_mb=item.get("memoryMB"),
                ))

            return templates

        except requests.exceptions.RequestException as e:
            raise Exception(f"调用模版列表API失败: {e}")
        except Exception as e:
            raise Exception(f"获取模版列表失败: {e}")

    def get_builds_by_template(self, template_id: str) -> List[BuildInfo]:
        """
        根据模版ID获取构建列表（使用新的builds接口）
        
        Args:
            template_id: 模版ID
            
        Returns:
            构建信息列表
            
        Raises:
            Exception: 当API调用失败时
        """
        url = f"{self.api_url}/templates/{template_id}/builds"

        try:
            response = requests.get(
                url,
                headers=self.headers,
                timeout=self.timeout
            )

            if response.status_code != 200:
                raise Exception(
                    f"HTTP {response.status_code}: {response.text}"
                )

            data = response.json()

            # 提取构建信息
            builds = []
            for build in data:
                builds.append(BuildInfo(
                    build_id=build.get("buildID", ""),
                    template_id=template_id,
                    status=build.get("status", "unknown"),
                    cpu_count=build.get("cpuCount"),
                    memory_mb=build.get("memoryMB"),
                    created_at=build.get("createdAt", None),
                    finished_at=build.get("finishedAt", None),
                    errMsg=build.get("errorMessage", None),
                    logs_count=0,  # 新接口不返回logs数量
                ))

            return builds

        except requests.exceptions.RequestException as e:
            raise Exception(f"调用构建列表API失败: {e}")
        except Exception as e:
            raise Exception(f"获取构建列表失败: {e}")

    def get_build_status(
            self,
            template_id: str,
            build_id: str,
            logs_offset: int = 0,
            level: Optional[str] = None
    ) -> BuildInfo:
        """
        获取特定构建的状态和日志
        
        Args:
            template_id: 模版ID
            build_id: 构建ID
            logs_offset: 日志偏移量，默认0
            level: 日志级别过滤 (可选: "debug", "info", "warn", "error")
            
        Returns:
            包含构建状态和日志的字典
            
        Raises:
            Exception: 当API调用失败时
        """
        url = f"{self.api_url}/templates/{template_id}/builds/{build_id}/status"
        params = {"logsOffset": logs_offset}
        if level:
            params["level"] = level

        try:
            response = requests.get(
                url,
                headers=self.headers,
                params=params,
                timeout=self.timeout
            )

            if response.status_code != 200:
                raise Exception(
                    f"HTTP {response.status_code}: {response.text}"
                )

            data = response.json()

            # 提取构建信息
            result = BuildInfo(
                build_id=build_id,
                template_id=template_id,
                status=data.get("status", "unknown"),
                cpu_count=data.get("cpuCount"),
                memory_mb=data.get("memoryMB"),
                created_at=data.get("createdAt", ""),
                finished_at=data.get("finishedAt", ""),
                errMsg=data.get("errorMessage", ""),
            )

            return result

        except requests.exceptions.RequestException as e:
            raise Exception(f"调用构建状态API失败: {e}")
        except Exception as e:
            raise Exception(f"获取构建状态失败: {e}")
            

测试脚本

                test_template_info.py
                
            

                """
测试 template_info_manager 工具
"""

import os

# 导入工具
from template_info_manager import TemplateInfoManager

# 设置测试环境变量（请替换为真实的API密钥）
# 替换为对应区域的域名
os.environ["E2B_DOMAIN"] = "sandbox-execute.gz.baidubce.com"
# 替换为用户自己的api_key
os.environ["E2B_API_KEY"] = "bce-v3/****************************"


def test_list_templates():
    """测试获取模版列表"""
    print("\n" + "=" * 70)
    print("测试: 获取模版列表")
    print("=" * 70)

    try:
        manager = TemplateInfoManager()
        print(f"API URL: {manager.api_url}")

        # 获取模版列表
        templates = manager.list_templates()
        print(f"\n找到 {len(templates)} 个模版")

        if templates:
            print(f"\n前{len(templates)}个模版:")
            latest_custom_template = None
            for template in templates[:]:
                if not template.public:
                    latest_custom_template = template
                print(f"  - ID: {template.template_id}")
                print(f"    名称: {template.template_name}")
                print(f"    创建时间: {template.created_at}")
                print(f"    模版类型: {"官方模版" if template.public else "自定义模版"}")
                print(f"    cpu: {template.cpu_count}")
                print(f"    mem_mb: {template.memory_mb}")
                print()

            return latest_custom_template
        else:
            print("无模版")
            return None
    except Exception as e:
        print(f"错误: {e}")
        import traceback
        traceback.print_exc()
        return None


def test_get_builds_by_template(template_id):
    """测试获取构建列表（使用新接口）"""
    print("\n" + "=" * 70)
    print("测试: 获取构建列表（新接口 GET /{templateID}/builds）")
    print("=" * 70)

    try:
        manager = TemplateInfoManager()

        # 使用新接口获取构建列表
        builds = manager.get_builds_by_template(template_id)

        print(f"\n模版ID: {template_id}")
        print(f"构建数量: {len(builds)}")
        #
        if builds:
            print("\n构建列表:")
            for build in builds[:]:  # 只显示前5个
                print(f"  - 构建ID: {build.build_id}")
                print(f"    状态: {build.status}")
                print(f"    cpu_count: {build.cpu_count}")
                print(f"    mem_mb: {build.memory_mb}")
                print(f"    创建时间: {build.created_at}")
                print(f"    完成时间: {build.finished_at or '进行中'}")
                print(f"    error_msg: {build.errMsg or 'none'}")
                print()
            return builds[0]
        else:
            print(f"template{template_id} 无构建记录")
            return None
    except Exception as e:
        print(f"错误: {e}")
        import traceback
        traceback.print_exc()
        return None


def test_get_build_status(template_id, build_id):
    """测试获取构建状态"""
    print("\n" + "=" * 70)
    print("测试: 获取构建状态")
    print("=" * 70)

    try:
        manager = TemplateInfoManager()

        # 获取构建状态
        status = manager.get_build_status(template_id, build_id)

        print(f"\n构建ID: {status.build_id}")
        print(f"模版ID: {status.template_id}")
        print(f"状态: {status.status}")

        # 使用格式化输出
        # print("\n格式化输出:")
        # manager.print_build_status(template_id, build_id)

    except Exception as e:
        print(f"错误: {e}")
        import traceback
        traceback.print_exc()


if __name__ == "__main__":
    print("\n" + "=" * 70)
    print(" E2B Template Info Manager - 测试")
    print("=" * 70)

    # 测试1: 获取模版列表
    template = test_list_templates()

    if template:
        # 测试2: 获取构建列表（新接口）
        build = test_get_builds_by_template(template.template_id)

        # 使用新接口返回的build进行后续测试
        if build:
            # 测试3: 获取构建状态
            test_get_build_status(template.template_id, build.build_id)

    print("\n" + "=" * 70)
    print(" 测试完成!")
    print("=" * 70)
            

使用自定义模版创建沙箱

如下是使用自定义模版创建沙箱的示例代码，执行文件操作、命令执行，针对用户模版中自定义的程序，用户可以使用sandbox.get_host(用户程序端口)，获取用户程序的访问端点，sandbox.get_info()._envd_access_token获取操作沙箱的access_token，用户需要将获取的token拼接到请求头X-Access-Token中，否则会出现403错误，文件操作、命令执行无需获取端点和token，sdk自动注入。

                Python
                
            

                import os
import time
from datetime import datetime

from e2b_code_interpreter import Sandbox
from e2b import FilesystemEventType

#   export E2B_DOMAIN="sandbox-execute.gz.baidubce.com"
#   export E2B_API_KEY="<你的 API Key>"
os.environ["E2B_DOMAIN"]="sandbox-execute.gz.baidubce.com"
os.environ["E2B_API_KEY"]="bce-v3/*************************"


def main():
    sandbox = Sandbox.create(
        template="test_custom_template_online",
        timeout=300,
    )
    vnc = sandbox.get_host(6080)  # 浏览器相关沙箱，获取浏览器的vnc端点
    https_vnc_url = f"https://{vnc}/vnc.html" # 拼接浏览器vnc链接
    print(f"vncURL: {https_vnc_url}")
    X_Access_Token = sandbox.get_info()._envd_access_token # 获取访问token，用户访问用户自定义程序
    result = sandbox.commands.run("whoami", user="docker") # user指定执行命令的用户
    print(result.stdout)
    
    # 命令执行，使用模版中自带的python解释器执行命令
    result = sandbox.commands.run("python3 -c \"print('Python3 is working!')\"", user="docker")
    print(result.stdout)
   

    # 文件操作
    print("Creating directory 'test_dir' ...")
    ret = sandbox.files.make_dir("test_dir", user="docker")
    print("make_dir result:", ret)

    # 写单文件
    print("Writing file test_dir/qs3.txt ...")
    sandbox.files.write(path="test_dir/qs3.txt", data="file content", user="docker")

    # 读取文件
    print("Reading test_dir/qs3.txt ...")
    file_content = sandbox.files.read("test_dir/qs3.txt", user="docker")
    print("Content of qs3.txt:", file_content)

    # 获取文件信息
    print("File info for test_dir/qs3.txt:")
    info = sandbox.files.get_info("test_dir/qs3.txt", user="docker")
    print(info)

    # 列目录
    print("\nListing user directory '/':")
    user_info = sandbox.files.get_info("/home", user="docker")
    print("user info:", user_info)

    user_files = sandbox.files.list("/home/docker", user="docker")
    print("user files:", user_files)

    # 判断是否存在
    print("\nChecking existence of test_dir/qs3.txt ...")
    exists = sandbox.files.exists("test_dir/qs3.txt", user="docker")
    print("exists?", exists)



    # -------- 命令执行操作 --------

    # 列出当前目录内容（详细）
    print("Running 'ls -la' ...")
    result = sandbox.commands.run("ls -la", user="docker")
    print("stdout:\n", result.stdout)
    

    print("Running 'echo hello; sleep 1; echo world' with streaming ...")
    result = sandbox.commands.run(
        "echo hello; sleep 1; echo world",
        user="docker",
        on_stdout=lambda data: print("STDOUT:", data),
        on_stderr=lambda data: print("STDERR:", data),
    )

    # 结束沙箱
    print("\nKilling sandbox...")
    sandbox.kill()
    print("Sandbox killed.")


if __name__ == "__main__":
    main()
            

说明

每个用户默认最多创建5个自定义模版，用户可以在同一个模版上执行多次构建，一个模版同时只允许存在一个正在构建的任务，用户最多同时存在两个正在构建的任务(不同模版)，用户创建沙箱时默认使用最近一次成功的构建。
自定义模版的构建过程是异步过程，暂时还不支持查看构建日志，ready表示构建成功、building表示构建中、error表示构建失败。
在资源正常的情况下，700MiB镜像的构建时间大约为2min，2G镜像的构建时间大约为5min。
模版资源限制，cpu最少为2G，最大为16G，内存最小为2048MiB，最大为16384MiB(16G)，cpu和内存比需按1:1/1:2/1:4的形式，例如cpu设置为2G，内存只能为2048、4096、8192。若需要使用16G cpu或16G memory，暂时只支持bj地域

Cpu	Memory
2	2048、4096、8192
4	4096、8192、16384
8	8192、16384
16	16384

电脑沙箱快速入门

操作指南

百度智能云

函数计算 CFC

函数计算 CFC

自定义沙箱快速入门

概览

安装依赖

指定镜像构建模版

基于模版构建新模版

基于命令构建模版

Dockerfile指令和sdk命令映射关系

查询模版列表、构建状态

使用自定义模版创建沙箱

说明

函数计算 CFC

自定义沙箱 快速入门

概览

安装依赖

指定镜像构建模版

基于模版构建新模版

基于命令构建模版

Dockerfile指令和sdk命令映射关系

查询模版列表、构建状态

使用自定义模版创建沙箱

说明

自定义沙箱快速入门