Skip to main content
How-to Guide

Manage and Use Instances

Manage the sandbox instance lifecycle and perform data-plane operations through the E2B SDK. Using the Bailian sandbox endpoint and API Key, create instances, run commands, execute code, and read/write files.

Sandbox is compatible with the E2B SDK. After installing the official E2B SDK, point the endpoint to the Bailian sandbox and authenticate with a Bailian API Key to create instances, run commands, execute code, and read/write files. The examples in this document are verified with the following versions:
pip install "e2b==2.31.0"
# For Code Interpreter capabilities such as run_code
pip install "e2b-code-interpreter==2.8.1"

Authentication and Endpoint

ParameterDescription
api_urlBailian sandbox endpoint, in the form https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sandbox
AuthorizationBearer <Bailian API Key>, used for real authentication
api_keyRequired parameter of the E2B SDK, only to match the SDK format; e2b_${ALIYUN_UID} is recommended
templateThe template code, i.e., the templateCode created in the console
api_key only needs to match the format e2b_ followed by hexadecimal characters. An Alibaba Cloud UID is numeric and naturally passes validation (for example, e2b_your aliyunUid). Bailian does not use api_key for business authentication.

Step 1: Create an Instance

Create a cloud sandbox from a template code using a Bailian API Key. On success, you get a sandbox_id used for all subsequent access and management.
from e2b import Sandbox

ALIYUN_UID = "your aliyunUid"
BAILIAN_API_KEY = "sk-..."
BASE_URL = "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sandbox"

sbx = Sandbox.create(
    api_url=BASE_URL,
    api_key=f"e2b_{ALIYUN_UID}",
    headers={"Authorization": f"Bearer {BAILIAN_API_KEY}"},
    template="your template code",
)

print(sbx.sandbox_id)

Step 2: Access the Instance

After connecting to the sandbox, run commands, execute code, and read/write files as if they were local.
# Run a command
result = sbx.commands.run("python --version")
print(result.stdout)

# Make a directory
sbx.files.make_dir("/home/user/workspace/e2b")

# Write a file
sbx.files.write(
    "/home/user/workspace/hello_bailian_sandbox.md",
    "hello bailian",
)

# Read a file
content = sbx.files.read(
    "/home/user/workspace/hello_bailian_sandbox.md"
)
print(content)

# Run code (requires e2b-code-interpreter)
execution = sbx.run_code("print(1 + 1)")
print(execution.text)

Step 3: Manage the Instance Lifecycle

Pause the sandbox when idle; reconnecting resumes it from the paused point. Release resources when no longer needed.
sandbox_id = sbx.sandbox_id

# Pause the sandbox, preserving file system and memory state
sbx.pause()

# Reconnect to the sandbox and continue using it
sbx = Sandbox.connect(
    sandbox_id=sandbox_id,
    api_url=BASE_URL,
    api_key=f"e2b_{ALIYUN_UID}",
    headers={"Authorization": f"Bearer {BAILIAN_API_KEY}"},
)

# Release the sandbox when no longer needed
sbx.kill()

Supported Capabilities

Instance Lifecycle

CapabilitySDK Method
Create instanceSandbox.create(template=...)
Get instance infosbx.get_info()
Connect to instanceSandbox.connect(sandbox_id=...)
Pause instancesbx.pause()
Release instancesbx.kill()

Data-Plane Operations

Data-plane operations are best performed through the SDK, which uses the domain and token returned by the connect call to reach the sandbox runtime directly.
CapabilitySDK MethodUnderlying Data-Plane Request
Run a commandsbx.commands.run(...)POST /process.Process/Start
Make a directorysbx.files.make_dir(path)SDK filesystem RPC
Write a filesbx.files.write(path, content)POST /files?path=...
Read a filesbx.files.read(path)GET /files?path=...
Run codesbx.run_code(...)POST :49999/execute
Template management has no stable SDK object methods; call the control-plane API over raw HTTP instead—see Sandbox API - Template Management. Instance lifecycle and data-plane operations use the SDK methods above.

Next Steps