使用 E2B SDK

OpenKruise Agents 的 sandbox-manager 组件支持两种 E2B 接入协议：原生 E2B 协议和私有协议。

sandbox-manager 的日常 E2E 回归测试通过 e2b-code-interpreter == 2.4.1 / e2b == 2.8.1 进行，同时通过 latest 版本测试兼容性。更新版本的新功能会逐步适配，如果有功能需求，请通过 GitHub 提交 issue。

私有协议与原生协议的对比：

假设您配置的 E2B_DOMAIN 是 your.domain.com

原生协议	私有协议
api.your.domain.com	your.domain.com/kruise/api
<port>-<sid>.your.domain.com	your.domain.com/kruise/<sid>/<port>

安装 Python SDK patch

下文的私有协议接入方式需要安装 kruise-agents Python 包。该包通过内存 monkey-patch 修改 E2B SDK，使其使用 OpenKruise 私有协议（不会修改磁盘上的 E2B 代码）。前置要求：

Python 3.9 及以上
e2b>=2.8.0
e2b-code-interpreter>=2.4.1

从 agents-api 仓库安装，并从 releases 页面选择版本 tag 固定版本。Python SDK 自 v0.6.0 起提供（可替换为您需要的版本）：

pip install git+https://github.com/openkruise/agents-api.git@v0.6.0#subdirectory=e2b/python

或从源码安装：

git clone https://github.com/openkruise/agents-api.git
cd e2b/python
pip install -e .

`patch_e2b` 的作用

在程序启动时调用一次 patch_e2b，之后再创建或连接任何 Sandbox。它会重写 SDK 构建的所有 URL：

流量	E2B 原生协议	patch 后
管理 API（create / kill / pause 等）	`https://api.<E2B_DOMAIN>`	`<scheme>://<E2B_DOMAIN>/kruise/api`
Sandbox 数据面（envd gRPC 与 HTTP、Jupyter）	`https://<port>-<sid>.<E2B_DOMAIN>`	`<scheme>://<E2B_DOMAIN>/kruise/<sid>/<port>`

<scheme> 默认为 https，传入 https=False 时为 http。https=False 还会将 sandbox 的 envd 和 Jupyter 基础 URL 强制为纯 HTTP，适用于无证书场景（集群内 Service 地址、kubectl port-forward）。

官方 E2B SDK 会在本地校验 API key 格式，只接受 e2b_ 前缀的 key，而 OpenKruise Agents 的 key 是裸 UUID 或 admin key。向 patch_e2b 传入 validate_key=False 可跳过本地格式校验（要求 e2b>=2.25.0），实际鉴权由服务端 sandbox-manager 完成。其他方式（例如使用 encode_for_e2b_sdk 包装 key）参见 API Keys 与 Teams。

配置 E2B 域名

基于域名接入的客户端需要配置 E2B_DOMAIN。服务端 sandbox-manager 支持两种域名模式：

动态解析（未传入参数时的默认模式）：当 --e2b-domain 为空时，sandbox-manager 根据每个请求的 HTTP Host 推导响应域名。原生协议请求会移除主机名开头的 api.，私有协议请求则保留完整主机名。因此，同一个 sandbox-manager 可以服务多个域名。
静态覆盖：当 --e2b-domain 非空时，服务端会原样返回该值并忽略请求主机名。所有客户端都通过同一个域名访问 sandbox-manager 时，可以使用此模式。

例如，在动态解析模式下，配置了 E2B_DOMAIN=example1.com 和 E2B_DOMAIN=example2.com 的客户端可以共用同一个 sandbox-manager。发往 api.example1.com 的请求会得到 example1.com 下的 Sandbox 地址，发往 api.example2.com 的请求则会得到 example2.com 下的地址。

备注

动态解析使用 HTTP Host 请求头，不信任 X-Forwarded-Host。请配置各级反向代理，使其保留 Host，或将 Host 重写为客户端所使用的公网访问地址。

配置服务端

默认部署清单使用动态解析，不传递 --e2b-domain。如果 Helm Chart 或已有 Deployment 设置了域名，请将其清空（例如使用 --set-string e2b.domain=""），或移除 --e2b-domain 参数以启用动态解析。

如果需要在通过 Helm 安装或升级 Sandbox Manager 时保留静态域名，请显式设置 e2b.domain：

helm install agents-sandbox-manager openkruise/agents-sandbox-manager \
  -n sandbox-system \
  --set e2b.domain=your.domain.com \
  --set e2b.adminApiKey=<your-api-key> \
  --set ingress.className=<your-ingress-class>

配置静态覆盖时，该值必须与客户端的 E2B_DOMAIN 相同。

配置客户端

您可以通过设置环境变量来配置客户端的 E2B_DOMAIN：

export E2B_DOMAIN=your.domain.com

特殊场景

1. 带端口的域名

对于 Ingress 网关不使用默认 HTTP 端口（80 或 443）的场景。例如，如果域名是 your.domain.com:8080：

客户端：设置 E2B_DOMAIN=your.domain.com:8080。
服务端使用动态解析时，会自动保留请求主机名中的端口。
服务端使用静态覆盖时，设置 --e2b-domain=your.domain.com:8080。
Ingress 的主机名规则使用不带端口的 your.domain.com。

2. 多域名

如果需要通过多个域名暴露同一个 sandbox-manager：

保持 --e2b-domain 为空，启用服务端动态解析。
为每个公网入口配置 DNS 和 Ingress 路由。原生协议使用默认的基于主机名的路由时，需要配置 api.<domain> 与 *.<domain>；使用私有协议时，需要配置基础域名。
准备覆盖所有入口的证书。自签名证书与 cert-manager 指南均提供了多域名示例。
将每个客户端的 E2B_DOMAIN 设置为该客户端实际连接的域名。

此场景不要设置静态 --e2b-domain，因为静态值会覆盖所有请求主机名。

如何安装证书

如果您需要通过 HTTPS 访问 sandbox-manager，需要安装 TLS 证书。建议使用可信证书。如果您没有可信证书，可以使用自签名证书，请参考以下文档：

使用 Helm Chart 部署时无需手动创建该 Secret：设置 enableTLS=true 后，Chart 会通过 cert-manager 签发 Ingress 证书，并写入 Ingress 引用的同一个 sandbox-manager-tls Secret。如需覆盖更多域名，可通过 --set e2b.extraDomains={example2.com} 传入，Chart 会自动推导全部 SAN，无需手动编辑 dnsNames。

您也可以使用以下命令手动安装证书：

# ingress-nginx 示例，根据您的 ingress controller 进行调整
kubectl create secret tls sandbox-manager-tls \
          --cert=fullchain.pem \
          --key=privkey.pem -n sandbox-system

推荐的 sandbox-manager 集成方式

1. 使用原生协议集成

这是最标准、最原生的集成方式，但配置门槛也最高，通常需要手动部署。

客户端配置环境变量：

# 如果服务端配置了静态 E2B 域名，其值必须与客户端相同
export E2B_DOMAIN=your.domain.com
export E2B_API_KEY=<your-api-key>

在您的 DNS 提供商处将通配符域名 *.your.domain.com 解析到 sandbox-manager 的 ingress 端点
安装通配符证书 *.your.domain.com

2. 私有协议从集群外通过 HTTPS 访问

这种方式可以降低部署门槛，将泛域名替换为了单域名。

客户端配置环境变量：

# 如果服务端配置了静态 E2B 域名，其值必须与客户端相同
export E2B_DOMAIN=your.domain.com
export E2B_API_KEY=<your-api-key>

修改客户端：

from kruise_agents.patch_e2b import patch_e2b
patch_e2b(https=True)

在您的 DNS 提供商处将单个域名 your.domain.com 解析到 sandbox-manager 的 ingress 端点
安装单个域名证书 your.domain.com

3. 使用 E2B URL 参数实现集群外访问

通过 E2B SDK 原生支持的 URL 参数从集群外直接访问 sandbox-manager 和 sandbox-gateway，无需通配符 DNS 或私有协议 patch。要求 e2b >= 2.7.0。

准备两个公网域名，并将其分别路由到对应的 Ingress 端点：
- api.your.domain.com：路由到 sandbox-manager 的控制面域名。api. 前缀是固定的，不能替换为其他子域名。
- gateway.your.domain.com：路由到 sandbox-gateway 的数据面域名。该域名可以使用任意子域名，推荐使用 gateway。
安装同时覆盖 api.your.domain.com 和 gateway.your.domain.com 的 TLS 证书。

配置客户端环境变量：

export E2B_API_URL="https://api.your.domain.com"
export E2B_SANDBOX_URL="https://gateway.your.domain.com"
export E2B_API_KEY=<your-api-key>

使用 E2B SDK 创建 Sandbox，无需额外 patch：

from e2b import Sandbox

# E2B_API_URL 和 E2B_SANDBOX_URL 会自动从环境变量读取
sandbox = Sandbox()
print(sandbox.get_host(8000))  # 获取 Sandbox 内服务的访问地址
sandbox.kill()

集群内配置

当客户端、sandbox-manager 和 sandbox-gateway 位于同一集群时，可以直接使用 Kubernetes Service 地址，好处是无需配置公网 DNS 解析：

export E2B_API_URL="http://sandbox-manager.sandbox-system.svc.cluster.local:8080"
export E2B_SANDBOX_URL="http://sandbox-gateway.sandbox-system.svc.cluster.local:7788"
export E2B_API_KEY=<your-api-key>

如果未安装外置的 sandbox-gateway，可以将 E2B_SANDBOX_URL 改为使用 sandbox-manager，继续使用其内置流量代理，但不推荐这种方式。

⚠️ 限制说明：上层库 e2b-code-interpreter 和 e2b-desktop 的以下扩展功能不读取 E2B_API_URL / E2B_SANDBOX_URL 环境变量，因此不支持这种 URL 参数接入方式：

e2b-code-interpreter：

Sandbox.run_code

Sandbox.create_code_context

Sandbox.remove_code_context

Sandbox.list_code_contexts

Sandbox.restart_code_context

e2b-desktop：

desktop.stream.get_url

desktop.stream.start

4. 私有协议集群内访问

这种方式可以快速自动化部署，无需配置域名和证书。仅推荐用于 E2E 测试场景，或经过严格评估后使用。

确保客户端（agent）和 sandbox-manager 在同一集群中。

客户端配置环境变量：

# 如果服务端配置了静态 E2B 域名，其值必须与客户端相同
export E2B_DOMAIN=sandbox-manager.sandbox-system.svc.cluster.local
export E2B_API_KEY=<your-api-key>

修改客户端并禁用 HTTPS：

from kruise_agents.patch_e2b import patch_e2b
patch_e2b(https=False)

5. 端口转发 sandbox-manager 到本地机器

客户端配置环境变量：

# 如果服务端配置了静态 E2B 域名，其值必须与客户端相同
export E2B_DOMAIN=localhost
export E2B_API_KEY=<your-api-key>

端口转发 sandbox-manager 到本地机器：

sudo kubectl port-forward services/sandbox-manager 80:7788 -n sandbox-system

修改客户端：

from kruise_agents.patch_e2b import patch_e2b
patch_e2b(https=False)

Traffic JWT 刷新

对于启用 Traffic JWT 认证的 Sandbox，独立的 patch_traffic_access_token patch 会将 token 保存在内存中，并在过期前自动刷新：

from kruise_agents.patch_e2b import patch_e2b
from kruise_agents.patch_traffic_token import patch_traffic_access_token

patch_e2b(https=False)
patch_traffic_access_token()

该 patch 要求 Python 3.10 及以上、e2b>=2.35.0,<2.38.0、e2b-code-interpreter>=2.9.0,<2.10.0。缩短 token 有效期或升级 sandbox-manager 时的部署顺序很重要，具体要求、显式刷新与 rollout 行为参见流量访问令牌轮换。

安装 Python SDK patch​

patch_e2b 的作用​

配置 E2B 域名​

配置服务端​

配置客户端​

特殊场景​

1. 带端口的域名​

2. 多域名​

如何安装证书​

推荐的 sandbox-manager 集成方式​

1. 使用原生协议集成​

2. 私有协议从集群外通过 HTTPS 访问​

3. 使用 E2B URL 参数实现集群外访问​

4. 私有协议集群内访问​

5. 端口转发 sandbox-manager 到本地机器​

Traffic JWT 刷新​

安装 Python SDK patch

`patch_e2b` 的作用

配置 E2B 域名

配置服务端

配置客户端

特殊场景

1. 带端口的域名

2. 多域名

如何安装证书

推荐的 sandbox-manager 集成方式

1. 使用原生协议集成

2. 私有协议从集群外通过 HTTPS 访问

3. 使用 E2B URL 参数实现集群外访问

4. 私有协议集群内访问

5. 端口转发 sandbox-manager 到本地机器

Traffic JWT 刷新