自定义沙箱快速入门

更新时间：2026-07-17

概览

本文将介绍如何使用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

自定义模版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

评价此篇文章

有帮助没帮助

电脑沙箱快速入门

操作指南

百度智能云

智能体沙箱 AX

智能体沙箱 AX

自定义沙箱快速入门

概览

安装依赖

指定镜像构建模版

基于模版构建新模版

基于命令构建模版

Dockerfile指令和Sdk命令映射关系

自定义模版ReadyCommand

Sdk ReadyCommand和系统命令映射关系

查询模版列表、构建状态

使用自定义模版创建沙箱

说明

智能体沙箱 AX

自定义沙箱 快速入门

概览

安装依赖

指定镜像构建模版

基于模版构建新模版

基于命令构建模版

Dockerfile指令和Sdk命令映射关系

自定义模版ReadyCommand

Sdk ReadyCommand和系统命令映射关系

查询模版列表、构建状态

使用自定义模版创建沙箱

说明

自定义沙箱快速入门