Volcengine Kubernetes Engine
Volcengine Kubernetes Engine
Volcengine Kubernetes Engine
Document
Volcengine Kubernetes Engine
What's New
History feature release notes
Kubernetes version release notes
Containerd runtime release notes
Add-on release notes
Monitoring add-ons
Scheduling add-ons
DNS add-ons
Security add-ons
GPU add-ons
Sandbox add-on
Security announcements
Product Announcement
Historical announcements
Overview
Getting started
User guide
Clusters
Creating clusters
Connecting to clusters
Upgrading clusters
Node pool
Creating node pools
Scaling out/in node pools
Nodes
Authorization management
Image
Namespaces
Networking
Cluster network
Container Network
Service
LoadBalancer
CLB
Ingress
APIG Ingress
ALB Ingress
Customize ALB Ingress forwarding rules
Certificate and security
CLB Ingress
Nginx Ingress
Gateway API
Workloads
Creating workloads
Configure workloads
Pods
Configuration management
Image acceleration
Storage
FSX client
EBS Volumes
TOS Volumes
NAS volumes
FSX access methods
NFS access methods
EFS volumes
vePFS volumes
FSX access methods
vePFS Client access methods
NFS access methods
CloudFS volumes
Local volumes
Autoscale
Node autoscaler
Workload autoscaler
Horizontal Pod Autoscaler (HPA)
Cron Horizontal Pod Autoscaler (CronHPA)
Intelligent Horizontal Pod Autoscaler (IHPA)
Horizontal Pod Autoscaler based on event-driven (KEDA)
Add-on management
Network add-ons
Storage add-ons
Monitoring add-ons
Scheduling add-ons
DNS add-ons
GPU add-ons
Core add-ons
Sandbox add-on
Upgrading add-ons
Heterogeneous computing
NVIDIA GPU
mGPU scheduling
RDMA high-performance computing
Scheduling management
Topology-aware scheduling
QoS-aware scheduling
Observability
Log management
Basic observation
Setup & Configuration
Cluster observation
Storage observation
Other observation
Using metrics
Full stack observation
Alert management
Diagnosis and inspection
Node check and self-healing
Application center
Backup center
Stability
Large-scale cluster management
Best practices
Authorization
Clusters
Nodes and node pools
Networking
Storage
Scheduling
Observability
Solution
Security and compliance
API reference
Cluster management
NodePool management
Node management
Virtual nodes management
Add-on management
Tag management
Access policy management
Instance images management
Cloud native observability
Inspection and diagnosis
Task management
Volcengine Container Instance
Appendix
SDK reference
Development guide
Terraform
FAQs
General FAQs
Cluster FAQ
cluster management
cluster network
cluster upgrade
Node and Node pool FAQs
Authorization FAQs
Workload FAQs
Service and Ingress FAQs
Storage FAQs
Heterogeneous computing FAQs
Observability FAQs
Quota FAQs
Add-on FAQs
Cloud-native AI
ServingKit
LLM applications
ComfyUI application
Deploying the Al inference application through Helm
Deepseek practices
Qwen practices
Kimi practice
Seed practices
Best practices
DeepSeek model deployment
GLM model deployment
MiniMax model deployment
Qwen model deployment
Kimi model deployment
Volcengine Container Instance
What's new
Historical feature release notes
Product Announcement
Overview
Billing
User guide
Integrating with VCI
Virtual node
VKE cluster uses virtual nodes
Self-managed/third-party cluster uses virtual node
Creating an instance
General purpose instance
GPU-accelerated computing instance
VCI Agent Sandbox
Startup acceleration
E2B-based management
Upgrade guide
Networking
Monitoring
Scheduling
Container configuration
VCI Image Cache
Best practices
Security and compliance
FAQs
- Documentation
Volcengine Kubernetes EngineVolcengine Container InstanceUser guideVCI Agent SandboxE2B-based managementSDK reference
Copy page
Download PDFE2B-based management
SDK reference
Copy pageDownload PDFSDK reference
This topic provides SDK-based development instructions for managing VCI Agent Sandbox by using the E2B protocol.
E2B compatibility
Category | API | Description | Compatibility | Compatibility remarks |
Category | API | Description | Compatibility | Compatibility remarks |
Sandbox lifecycle | create | Creates a VCI Agent Sandbox. | Partially compatible | The following capabilities are not supported: network access control, in-place configuration change, and automatic pause. |
Sandbox lifecycle | get_info | Queries VCI Agent Sandbox instance information. | Fully compatible | None |
Sandbox lifecycle | list | Lists all VCI Agent Sandbox information. | Fully compatible | None |
Sandbox lifecycle | delete | Deletes the specified VCI Agent Sandbox instance. | Fully compatible | None |
Sandbox lifecycle | connect | Connects to the specified VCI Agent Sandbox instance. | Fully compatible | None |
Sandbox lifecycle | pause | Pauses the specified VCI Agent Sandbox instance. This interface is asynchronous. When the interface call is successful, the underlying Pod for the Sandbox is reclaimed while the snapshot is still being created. | Fully compatible | None |
Sandbox lifecycle | resume | Resumes the VCI Agent Sandbox instance. Data will be automatically restored from the writable layer snapshot generated during the last pause. | Fully compatible | None |
File system | write | The e2b-code-interpreter component needs to run in the primary container. You can view the definition of the e2b-code-interpreter component in the initcontainer of the template. | Fully compatible | In addition to defining relevant settings in the initcontainer field in the template, you can also use the annotation agent.sandbox.io/enable-envd-injection: "true" to allow VCI to automatically inject the envd program. |
File operations | read | | Fully compatible | |
Code execution | run_code | | Fully compatible | |
Command execution | commands.run | | Fully compatible | |
API Key management | - | Because the E2B code interpreter SDK does not include API Key management functionality, relevant operations are typically performed via the E2B web console, E2B CLI, or HTTP requests. VCI Agent Sandbox primarily supports HTTP request methods, including POST, DELETE, and GET. | N/A | None |
Template management | post_templates | Creates the template based on the complete SandboxTemplate structure constructed. | Fully compatible | None |
| requests.delete | Deletes the specified template. This interface is not available in the native E2B SDK. We recommend using the API to operate on templates. | N/A | None |
| requests.patch | Updates the specified template. This interface is not available in the native E2B SDK. We recommend using the API to operate on templates. | N/A | None |
| requests.get | Queries the details of a single template. This interface is not available in the native E2B SDK. We recommend using the API to operate on templates. | N/A | None |
Snapshot management | create_snapshot | Creates a snapshot. | Fully compatible | None |
| requests.delete | Deletes a snapshot. | No compatibility | None |
| list_snapshot | Queries a list of snapshots. It returns only snapshots that have been created and are available. | Fully compatible | None |
Monitoring | get_metrics | Queries Sandbox monitoring data. | Partially compatible | You cannot specify a start or end time. |
E2B SDKs
The official E2B website provides multiple SDK integration methods, such as e2b and e2b_code_interpreter. For the scenario described in this topic, we recommend using e2b_code_interpreter, which comes pre-installed with Python libraries for data analysis.
pip install e2b-code-interpreter==2.4.1 e2b==2.10.2 anthropic python-dotenv
All code samples in this topic are in Python. For code samples in other programming languages, see the E2B documentation.
Standard E2B capabilities
Sandbox lifecycle
Create Sandboxes
Query Sandboxes
Delete Sandboxes
Pause Sandboxes
Resume Sandboxes
Request body parameters
Parameter Name | Type | Required | Description |
Parameter Name | Type | Required | Description |
template | string | Yes | The template ID used for Sandbox creation. |
timeout | int | No | Sandbox lifetime:
|
metadata | Dict[str, str] | No | Additional annotations that need to be added to the Sandbox. |
secure | bool | No | Specifies whether to enable envd authentication for the Sandbox:
|
Response parameters
Parameter Name | Type | Description |
Parameter Name | Type | Description |
SandboxInfo | Class | The class containing basic sandbox information. For sub-parameter descriptions, see the SandboxInfo section of this topic. |
SandboxInfo
Parameter Name | Type | Description |
Parameter Name | Type | Description |
template_id | string | The template ID used for Sandbox creation. |
sandbox_id | string | The ID of the Sandbox instance. |
envd_version | string | The envd version used. |
_envd_access_token | string | envd authentication information. |
domain | string | The domain name for accessing the E2B API. |
Examples
def create_sandbox(template):
sbx = Sandbox.create(template=template, secure=True)
print("created sandbox_id=", sbx.sandbox_id)
return sbx
Response parameters
Parameter Name | Type | Description |
Parameter Name | Type | Description |
SandboxInfo | Class | The class containing basic sandbox information. For sub-parameter descriptions, see the SandboxInfo section of this topic. |
SandboxInfo
Parameter Name | Type | Description |
Parameter Name | Type | Description |
template_id | string | The template ID used for Sandbox creation. |
sandbox_id | string | The ID of the Sandbox instance. |
envd_version | string | The envd version used. |
_envd_access_token | string | envd authentication information. |
domain | string | The domain name for accessing the E2B API. |
Examples
def get_sandbox_info(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
info = sbx.get_info()
print("sandbox_id=", info.sandbox_id)
print("template_id=", info.template_id)
print("state=", info.state)
print("started_at=", info.started_at)
print("end_at=", info.end_at)
print("metadata=", info.metadata)
Examples
def delete_sandbox(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
ok = sbx.kill()
print("killed:", ok)
Examples
def pause_sandbox(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
sbx.beta_pause()
Request path parameter
Parameter Name | Type | Required | Description |
Parameter Name | Type | Required | Description |
sandboxId | string | Yes | The ID of the Sandbox instance. |
Response parameters
Parameter Name | Type | Description |
Parameter Name | Type | Description |
SandboxInfo | Class | The class containing basic sandbox information. For sub-parameter descriptions, see the SandboxInfo section of this topic. |
SandboxInfo
Parameter Name | Type | Description |
Parameter Name | Type | Description |
template_id | string | The template ID used for Sandbox creation. |
sandbox_id | string | The ID of the Sandbox instance. |
envd_version | string | The envd version used. |
_envd_access_token | string | envd authentication information. |
domain | string | The domain name for accessing the E2B API. |
Examples
def resume_sandbox(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
File system
Upload files
Download files
Examples
def upload_file(sbx):
with open("./test.txt", "rb") as file:
sbx.files.write("/test.txt", file)
Examples
def read_file(sbx):
file_content = sbx.files.read("/test.txt")
print(file_content)
Code execution
Code execution
Examples
def run_code(sbx):
sbx.run_code("print('hello world')")
Command execution
Command execution
Examples
def run_command(sbx):
sbx.commands.run('echo hello')
API Key management
VCI supports HTTP request methods such as POST, DELETE, and GET.
Create API Keys
Delete API Keys
Query API Keys
Examples
# API Key configuration.
API_BASE_URL = os.getenv("API_BASE_URL", "your.domain")
ADMIN_API_KEY = os.getenv("ADMIN_API_KEY", "sk-local-test-123456")
# API request headers.
headers = {
"X-API-KEY": ADMIN_API_KEY,
"Content-Type": "application/json"
}
def create_api_key(name):
"""Create a new API key"""
url = f"{API_BASE_URL}/api-keys"
payload = {"name": name}
print(f"Creating API key: {name}")
response = requests.post(url, headers=headers, json=payload)
Examples
url = f"{API_BASE_URL}/api-keys/{key_id}"
headers = {
"X-API-KEY": ADMIN_API_KEY,
"Content-Type": "application/json"
}
response = requests.delete(url, headers=headers)
Examples
url = f"{API_BASE_URL}/api-keys"
headers = {
"X-API-KEY": ADMIN_API_KEY,
"Content-Type": "application/json"
}
print(f"Getting API key list...")
response = requests.get(url, headers=headers)
Template management
Create templates
Delete templates
Update templates
Query details of a template
Examples
from e2b.connection_config import ConnectionConfig
from e2b.api.client_sync import get_api_client
from e2b.api.client.api.templates import post_templates
from e2b.api.client.models import TemplateBuildRequest
"""
使用官方 E2B SDK 创建 SandboxTemplate
Args:
api_base_url: E2B API 服务基础地址
api_key: API 认证密钥
template_name: 模版名称
namespace: Kubernetes 命名空间（默认 default）
template_spec: 可选的模版 spec 配置
"""
# 2. Configure the template spec.
if template_spec is None:
template_spec = {
"podTemplate": {
"metadata": {
"annotations": {
"agent.sandbox.io/snapshot-max-num": "2",
"vci.vke.volcengine.com/enable-auto-create-imc": "true",
"vci.vke.volcengine.com/preferred-instance-family": "vci.u1,vci.n3i",
"vci.volcengine.com/persistent-container": "true",
"vci.volcengine.com/tls-enable": "false",
"vci.volcengine.com/usable-disk-capacity": "40",
"vke.volcengine.com/burst-to-vci": "enforce"
}
},
"spec": {
"containers": [
{
"env": [
{"name": "ENVD_DIR", "value": "/mnt/envd"},
{"name": "PORT", "value": "49999"}
],
"image": "cr-cn-guilin-boe.volces.com/vke/code-interpreter:v0.1.0",
"lifecycle": {
"postStart": {
"exec": {
"command": ["/bin/bash", "-c", "/mnt/envd/envd-run.sh"]
}
}
},
"name": "main",
"resources": {
"limits": {"cpu": "2", "memory": "4Gi"},
"requests": {"cpu": "2", "memory": "4Gi"}
},
"volumeMounts": [
{"mountPath": "/mnt/envd", "name": "envd-volume"}
]
}
],
"initContainers": [
{
"command": ["sh", "/workspace/entrypoint.sh"],
"env": [
{"name": "ENVD_DIR", "value": "/mnt/envd"},
{"name": "__IGNORE_RESOURCE__", "value": "true"}
],
"image": "helm-cr-cn-guilin-boe.cr.volces.com/vke/agent-runtime:v0.0.4",
"name": "runtime",
"restartPolicy": "Always",
"volumeMounts": [
{"mountPath": "/mnt/envd", "name": "envd-volume"}
]
}
],
"terminationGracePeriodSeconds": 1,
"volumes": [{"emptyDir": {}, "name": "envd-volume"}]
}
}
}
# 3. Create the complete SandboxTemplate structure.
sandbox_template = {
"apiVersion": "extensions.agents.x-k8s.io/v1alpha1",
"kind": "SandboxTemplate",
"metadata": {
"name": template_name,
"namespace": namespace
},
"spec": template_spec
}
# 4. Initialize the E2B SDK connection configuration.
try:
config = ConnectionConfig(
api_key=api_key,
api_url=api_base_url
)
# Obtain the API client.
api_client = get_api_client(
config,
require_api_key=True,
require_access_token=False
)
print(f" ✅ SDK 连接初始化成功！")
except Exception as e:
print(f" ❌ SDK 连接初始化失败: {e}")
return None
# 5. Construct an SDK request object.
# (Required) TemplateBuildRequest must include the dockerfile field. Even if the custom server does not use this field, you need to provide an empty value.
build_request = TemplateBuildRequest(
dockerfile=""
)
build_request["namespace"] = namespace
build_request["sandboxTemplate"] = sandbox_template
print(f" ✅ 请求对象构建成功！")
# 6. Call the official SDK interface to create the template.
# To obtain the complete response, use sync_detailed.
response = post_templates.sync_detailed(
body=build_request,
client=api_client
)
Examples
# Template request format: namespace--template-id
template_path = f"{namespace}--{template_id}"
url = f"{api_base_url}/templates/{template_path}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json",
}
params = {}
if owner:
params["owner"] = owner
response = requests.delete(url, headers=headers, params=params)
The native E2B SDK update interface only supports switching between the public and private states. In contrast, the E2B management functionality of the VCI Agent Sandbox supports modifying more template property definitions.
warning
- When updating a template, construct a complete request by referring to the request parameters for template creation.
- When modifying the annotations or containers configuration, you need to pass in all information under the corresponding configuration block, even if only a single field within the block is adjusted.
Examples
import os
import sys
from e2b.connection_config import ConnectionConfig
from e2b.api.client_sync import get_api_client
from e2b.api.client.api.templates import patch_templates_template_id
from e2b.api.client.models import TemplateUpdateRequest
"""
使用 E2B SDK 修改模板
"""
template_path = f"{namespace}--{template_id}"
# 1. Create a connection configuration.
config = ConnectionConfig(
api_key=api_key,
api_url=api_base_url
)
# 2. Obtain the API client.
api_client = get_api_client(
config,
require_api_key=True,
require_access_token=False
)
# 3. Create the update request object.
update_request = TemplateUpdateRequest()
# Similarly to template creation, create a complete request payload.
# Only containers/annotations-level granular modifications are supported. To modify any field in the containers, pass in all fields of the containers structure.
# It contains the namespace and sandboxTemplate fields.
sandbox_template = {
"apiVersion": "extensions.agents.x-k8s.io/v1alpha1",
"kind": "SandboxTemplate",
"metadata": {
"name": template_id,
"namespace": namespace
},
"spec": {
"podTemplate": {
"spec": {
"containers": [
{
"name": "main",
"image": new_image
}
]
}
}
}
}
payload = {
"namespace": namespace,
"sandboxTemplate": sandbox_template
}
# Add the fields to update_request by using additional_properties.
update_request["namespace"] = namespace
update_request["sandboxTemplate"] = sandbox_template
# Send the request.
print(f"\n🚀 发送更新请求...")
url = f"{api_base_url}/templates/{template_path}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json"
}
try:
response = requests.patch(url, headers=headers, json=payload)
Examples
# Template request format: namespace--template-id
template_path = f"{namespace}--{template_id}"
url = f"{api_base_url}/templates/{template_path}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json",
}
response = requests.get(url, headers=headers)
Response result
{
"templateID": "template-13ec94e0-ab32-4a26-837d-f0167ffb1004",
"public": false, // Templates cannot be set as public or private.
"aliases": [
"template-13ec94e0-ab32-4a26-837d-f0167ffb1004"
],
"names": [
"template-13ec94e0-ab32-4a26-837d-f0167ffb1004"
],
"createdAt": "2026-05-05T14:54:28Z",
"updatedAt": "2026-05-05T14:54:28Z",
"lastSpawnedAt": null, // Recording the time of the template use is not supported.
"spawnCount": 0, // It does not support querying the number of times the template has been used.
"builds": [
{
"buildID": "a9d48185-53f6-4baf-b0d4-e273e5230c66",
"status": "ready"
}
]
}
Snapshot management
Create snapshots
Delete snapshots
Query snapshots
Response parameters
Parameter Name | Type | Description |
Parameter Name | Type | Description |
SandboxInfo | Class | The class containing basic sandbox information. For sub-parameter descriptions, see the SandboxInfo section of this topic. |
SandboxInfo
Parameter Name | Type | Description |
Parameter Name | Type | Description |
snapshotId | string | The snapshot ID. |
Examples
def create_snapshot(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id)
snap_shot_info = sbx.create_snapshot()
Request path parameter
Parameter Name | Type | Required | Description |
Parameter Name | Type | Required | Description |
sandboxId | string | Yes | The ID of the Sandbox instance. |
Examples
def delete_snapshot(snapshot_id: str) -> None:
"""
api_base_url: E2B API 服务基础地址
api_key: API 认证密钥
"""
url = f"{api_base_url}/snapshots/{snapshot_id}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json",
}
response = requests.delete(url, headers=headers)
Examples
def list_snapshot(sandbox) -> None:
paginator = sbx.list_snapshots()
while paginator.has_next:
snapshots = paginator.next_items()
print(snapshots)
Monitoring
Get metrics
Response parameters
Parameter Name | Type | Description |
Parameter Name | Type | Description |
List[SandboxMetrics] | List | The list containing basic sandbox information. For sub-parameter descriptions, see the SandboxMetrics section of this topic. |
SandboxMetrics
Parameter Name | Type | Description |
Parameter Name | Type | Description |
cpu_count | Integer | The total CPU cores of the sandbox. |
cpu_used_pct | Float | The CPU utilization of the sandbox. |
disk_total | Integer | The total disk size of the sandbox. |
disk_used | Integer | The disk size used by the sandbox. |
mem_total | Integer | The total memory of the sandbox. |
mem_used | Integer | The memory size used by the sandbox. |
timestamp | DataTime | The metric timestamp. |
Examples
def metrics_operation(sbx):
res = sbx.get_metrics()
print(res)
Last updated: 2026.08.05 15:41:03
All rights reserved © Beijing Volcano Engine Technology Co., Ltd2024
