自定义沙箱快速入门

更新时间：2026-02-10

概览

本文将介绍如何使用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	set_workdir()
USER	set_user()
ENV	set_envs()
CMD / ENTRYPOINT	set_start_cmd()

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

创建沙箱快照模版

用户可以基于正在运行的沙箱创建模版，沙箱服务会对正在运行的沙箱执行快照功能，并将其保存为模版，用户后续可以使用该模版创建新的沙箱，此处以api形式提供该功能

                Python
                
            

                POST /v1/sandbox/templates/snapshot   HTTP/1.1
Host: sandbox-execute.gz.baidubce.com
Authorization/X-API-Key: 用户自己的api_key

{
    "templateId": "test_snapshot_template",    # 要创建的模版id
    "sandboxId": "xjaksdjwqdkdca"              # 正在运行的沙箱
}
            

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名称	类型	是否必需	参数位置	描述
templateId	String	是	Body参数	要创建的模版名
sandboxId	String	是	Body参数	正在运行的沙箱

响应头域

除公共头域，无其它特殊头域。

响应参数 无

工具脚本

                Python
                
            

                import os
import requests
from typing import Any, Dict


class TemplateManager:
    @classmethod
    def create_snapshot_template(
        cls,
        template_id: str,
        sandbox_id: str,
        timeout: int = 180,
    ) -> Dict[str, Any]:
        e2b_domain = os.environ.get("E2B_DOMAIN")
        e2b_api_key = os.environ.get("E2B_API_KEY")

        if not e2b_api_key:
            raise ValueError("E2B_API_KEY未设置")
        if not e2b_domain:
            raise ValueError("E2B_DOMAIN未设置")

        if not template_id:
            raise ValueError("template_id不能为空")
        if not sandbox_id:
            raise ValueError("sandbox_id不能为空")

        api_domain = f"api.{e2b_domain}"
        url = f"https://{api_domain}/v1/sandbox/templates/snapshot"

        headers = {
            "X-API-Key": e2b_api_key,
            "Content-Type": "application/json",
            "Accept": "application/json"
        }

        payload = {
            "templateId": template_id,
            "sandboxId": sandbox_id,
        }

        try:
            response = requests.post(url, headers=headers, json=payload, timeout=timeout)
        except requests.exceptions.RequestException as e:
            raise Exception(f"调用创建快照模版接口失败: {e}")

        if response.status_code != 201:
            raise Exception(
                f"创建快照模版失败: HTTP {response.status_code}, "
                f"响应: {response.text}"
            )

        if not response.text:
            return {}

        try:
            return response.json()
        except ValueError:
            return {}

    @classmethod
    def delete_template(
        cls,
        template_id: str,
        timeout: int = 180,
    ) -> None:
        """Delete a snapshot template
        
        Args:
            template_id: The ID of the template to delete
            timeout: Request timeout in seconds (default: 180)
            
        Raises:
            ValueError: If required environment variables or parameters are missing
            Exception: If the API request fails
        """
        e2b_domain = os.environ.get("E2B_DOMAIN")
        e2b_api_key = os.environ.get("E2B_API_KEY")

        if not e2b_api_key:
            raise ValueError("E2B_API_KEY未设置")
        if not e2b_domain:
            raise ValueError("E2B_DOMAIN未设置")

        if not template_id:
            raise ValueError("template_id不能为空")

        api_domain = f"api.{e2b_domain}"
        url = f"https://{api_domain}/v1/sandbox/templates/{template_id}"

        headers = {
            "X-API-Key": e2b_api_key,
            "Content-Type": "application/json",
            "Accept": "application/json"
        }

        try:
            response = requests.delete(url, headers=headers, timeout=timeout)
        except requests.exceptions.RequestException as e:
            raise Exception(f"调用删除模版接口失败: {e}")

        if response.status_code != 204:
            raise Exception(
                f"删除模版失败: HTTP {response.status_code}, "
                f"响应: {response.text}"
            )
            

测试脚本

                Python
                
            

                import os
from datetime import datetime

from e2b_code_interpreter import Sandbox
from templateManager import TemplateManager

# Set up environment variables
os.environ["E2B_DOMAIN"] = "sandbox-execute.gz.baidubce.com"
os.environ["E2B_API_KEY"] = "bce-v3/************"


def create_template_from_sandbox(templateId: str):
    """
    Test Case 1: Create a sandbox, execute commands, then create a template from it
        
      This test verifies the workflow:
      1. Create a code sandbox
      2. Run commands to set up sandbox state
       3. Create a snapshot template from the sandbox
    """

    print("\n=== Test Case 1: Create Template from Sandbox ===")

    # Step 1: Create a new sandbox
    print("Step 1: Creating sandbox...")
    start = datetime.now()
    sandbox = Sandbox.create(
        template="code-interpreter-v1",
        timeout=int(os.environ.get("SANDBOX_TIMEOUT", "600")),
        headers={"X-BCE-AGENT-SANDBOX-GRAY": "TRUE"},
    )
    end = datetime.now()
    info = sandbox.get_info()
    sandbox_id = info.sandbox_id
    print(f"✓ Sandbox created: {sandbox_id}, time_diff{end - start}")

    # Step 2: Run commands in sandbox to set up state
    print("Step 2: Setting up sandbox state...")
    result = sandbox.commands.run("echo hello-from-sandbox > /home/user/hello.txt; ls -la /home/user")
    print(f"✓ Command executed:\n{result.stdout}")

    # Step 3: Create snapshot template from sandbox
    print(f"Step 3: Creating snapshot template '{templateId}' from sandbox...")
    resp = TemplateManager.create_snapshot_template(
        template_id=templateId,
        sandbox_id=sandbox_id,
    )
    print(f"Response: {resp}")

    # Step 4: Clean up
    print("Step 4: Cleaning up...")
    sandbox.kill()
    print("✓ Sandbox killed")


if __name__ == "__main__":
    create_template_from_sandbox("custom_snapshot_template")
            

注意：与其他模版不同，快照模版目前是同步创建，创建完成后用户可以在控制台查看，使用方式与其他自定义模版无区别。

自定义模版ReadyCommand

为了确保用户自定义模版沙箱创建时，沙箱内的程序处于ready状态，即沙箱创建成功即可访问沙箱内的自定义程序，此处提供readyCommand的支持，用户可以在构建自定义模版时自定义readyCommad，沙箱创建时系统会等待readyCommand执行成功后才返回沙箱。

                Python
                
            

                from e2b import Template, wait_for_timeout, wait_for_process, wait_for_file, wait_for_timeout

import os

os.environ["E2B_DOMAIN"] = "sandbox-execute.gz.baidubce.com"
os.environ["E2B_API_KEY"] = "bce-v3/*********************"

template = Template().from_image(
    image="ccr-*************.cnc.gz.baidubce.com/**********/ubuntu2204_python312:v1",
).set_ready_cmd("sleep 3")      # sleep 3秒后启动，等价于wiat_for_timeout(3000)
# 
buildIf = Template.build_in_background(template,
                                       alias="template_with_python312",
                                       cpu_count=2,
                                       memory_mb=4096)
            

Sdk ReadyCommand和系统命令映射关系

Sdk	系统命令
wait_for_timeou(3000)	sleep 3
wait_for_prot(8080)	ss -tuln \| grep :8080
wait_for_file("/tmp/ready")	[ -f /tmp/ready ]
wait_for_process("python")	pgrep python > /dev/null

查询模版列表、构建状态

用户可以在cfc控制台查看自定义模版列表及构建状态

使用自定义模版创建沙箱

如下是使用自定义模版创建沙箱的示例代码，执行文件操作、命令执行，针对用户模版中自定义的程序，用户可以使用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。

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

百度智能云

函数计算 CFC

函数计算 CFC

自定义沙箱快速入门

概览

安装依赖

指定镜像构建模版

基于模版构建新模版

基于命令构建模版

Dockerfile指令和Sdk命令映射关系

创建沙箱快照模版

自定义模版ReadyCommand

Sdk ReadyCommand和系统命令映射关系

查询模版列表、构建状态

使用自定义模版创建沙箱

说明

函数计算 CFC

自定义沙箱 快速入门

概览

安装依赖

指定镜像构建模版

基于模版构建新模版

基于命令构建模版

Dockerfile指令和Sdk命令映射关系

创建沙箱快照模版

自定义模版ReadyCommand

Sdk ReadyCommand和系统命令映射关系

查询模版列表、构建状态

使用自定义模版创建沙箱

说明

自定义沙箱快速入门