Skip to main content

访问沙箱

当 Sandbox 被交付后（参见 Sandbox 申领），客户端会向其发送流量，用于运行代码、执行命令、 读写文件，或访问 Sandbox 内某个端口上监听的服务。本页介绍入方向流量如何到达 Sandbox、由哪些安全凭证保护，以及可用于 连接的三种 SDK，并说明如何通过端口转发将流量映射到本地进行调试。

域名、TLS 和多域名部署的细节请参见使用 E2B SDK。本页聚焦于访问链路本身，相关内容以链接方式引用， 不再重复。

入方向流量架构​

OpenKruise Agents 将入方向流量拆分为控制面和数据面，从而保证控制面的问题不会中断已经流向运行中 Sandbox 的 业务流量。

平面组件职责原生协议地址私有协议地址
控制面sandbox-managerE2B/MCP 管理 API：create、kill、pause、resume、connect、list、API Keyapi.<domain><domain>/kruise/api
数据面sandbox-gateway将流量代理进运行中的 Sandbox（envoy filter）<port>-<sandboxID>.<domain><domain>/kruise/<sandboxID>/<port>

入方向流量架构：控制面经由 sandbox-manager，数据面经由 sandbox-gateway

  • 控制面使用 API Key 鉴权，返回 Sandbox 地址及其数据面凭证。
  • 数据面承载真正的命令、文件、代码执行以及自定义服务流量。sandbox-gateway 将每个请求路由到目标 Sandbox，默认 转发到监听 49983 端口的 agent-runtime（envd）sidecar。命令和文件操作需要注入 agent-runtime，参见 Runtime 注入。
  • 当控制面请求到达 sandbox-gateway 时，它会将请求转发给 sandbox-manager。因此 gateway Service 可以作为两个平面在 7788 端口上的单一入口。

数据面路由​

sandbox-gateway 按以下优先级解析目标 Sandbox：

  1. 基于 Header（优先）。 设置 e2b-sandbox-id（必填）和 e2b-sandbox-port（可选，默认为 envd 端口 49983）。 Header 路由不依赖 DNS 泛解析，也是各 SDK 底层使用的方式。
  2. 基于域名（兜底）。 原生协议主机名 <port>-<sandboxID>.<domain>，或私有协议路径 <domain>/kruise/<sandboxID>/<port>。

<sandboxID> 默认为 namespace--name；启用短 Sandbox ID 后则为不透明的短 ID。请将其视为精确匹配的 不透明值。

原生协议基于主机名的路由需要泛域名 DNS（*.<domain>）和泛域名证书。私有协议只需要单一域名和单一证书，降低了测试与 快速集成的部署门槛。

访问凭证​

不同凭证保护不同的平面。它们都属于敏感信息：不要写入日志，也不要存进 Sandbox metadata。

凭证保护对象Header / 环境变量来源
API Key控制面X-API-KEY 头、E2B_API_KEY 环境变量以 adminApiKey 引导，或通过 API Key 端点按团队签发
envd 访问令牌数据面（静态）X-Access-Tokencreate 响应中以 envdAccessToken 返回；与 Sandbox 生命周期绑定
流量访问令牌数据面（JWT）E2B-Traffic-Access-Token短期、可刷新的 JWT；参见流量访问令牌轮换
Runtime 令牌数据面（直连 envd）X-Access-Token存储在 Sandbox CR 注解 agents.kruise.io/runtime-access-token 上
  • API Key。 每一次对 sandbox-manager 的管理调用都要设置 X-API-KEY。原生 E2B SDK 从 E2B_API_KEY 读取。管理员 Key 拥有更高权限；日常工作请优先使用按团队划分范围的 Key。E2B SDK >= 2.25.0 会在客户端校验 e2b_[0-9a-f]+ 的 Key 格式；旧版 Key 的处理方式参见 API Key 与团队管理。
  • envd 访问令牌（静态）。 与 Sandbox 绑定的长期不透明令牌。原生 E2B SDK 会在 run_code、commands、files 调用中 自动注入，因此大多数客户端无需直接处理它。它在 Sandbox 被删除前一直有效。
  • 流量访问令牌（JWT）。 静态令牌的可选替代，短期、可刷新，按 Sandbox 启用。它将重放风险限制在 JWT 有效期窗口内。刷新 行为和客户端要求见流量访问令牌轮换。
  • Runtime 令牌。 仅由 Runtime SDK 使用，它直连 envd。当具备 kubeconfig 或集群内访问能力时， Runtime 客户端可以直接从 Sandbox CR 注解读取该令牌。

访问方式​

根据部署方式以及所需的 E2B 能力范围选择合适的 SDK。

方式包路由适用场景
原生 E2B SDKe2b、e2b-code-interpreter域名 / Header标准生产集成，完整 E2B API
私有协议 SDKkruise_agents.patch_e2b路径（/kruise/...）单域名部署、测试、快速集成
Runtime SDKgithub.com/openkruise/agents-api/runtime直连 envd直接对运行中的 Sandbox 执行命令和文件操作

安装 Python 客户端：

# 原生 E2B SDK
pip install "e2b" "e2b-code-interpreter"

# OpenKruise Agents 私有协议扩展，来自 agents-api 仓库。
# 将 <version> 替换为 agents-api 的发布标签。
pip install "git+https://github.com/openkruise/agents-api.git@<version>#subdirectory=e2b/python"

1. 原生 E2B SDK​

标准集成方式。客户端从控制面解析 Sandbox，并通过 *.<domain>（或等价的 Header）发送数据面流量。设置域名和 API Key 后， 按常规方式使用 SDK：

export E2B_DOMAIN=your.domain.com
export E2B_API_KEY=<your-api-key>
from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(template="code-interpreter")
print("sandbox id:", sbx.sandbox_id)

execution = sbx.run_code("print('hello, world')")
print("run code result:", execution)

# Sandbox 内监听 8000 端口的服务访问 URL
print(sbx.get_host(8000))

sbx.kill()

envdAccessToken 会自动返回并注入到 run_code、commands、files 调用中，无需手动处理令牌。原生协议部署需要泛域名 DNS 和泛域名证书，参见使用 E2B SDK。

2. 私有协议 SDK​

私有协议只保留单一域名并按路径路由（<domain>/kruise/<sandboxID>/<port>），因此只需要一张证书。请在导入 E2B Sandbox 类 之前应用补丁：

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)   # 从集群外通过 HTTPS 访问

from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(template="code-interpreter")
execution = sbx.run_code("print('hello, world')")
print(execution)
sbx.kill()
  • 对于集群内访问或本地端口转发（TLS 在别处终止）的场景，使用 patch_e2b(https=False)。
  • 若要在 E2B SDK >= 2.25.0 上复用旧版（非 e2b_）API Key，传入 validate_key=False： patch_e2b(https=True, validate_key=False)。
  • 若需要自动刷新 JWT，在 patch_e2b 之后追加流量令牌补丁，参见 流量访问令牌轮换。

3. Runtime SDK（直连 envd）​

Runtime SDK 绕过 E2B 协议，直接操作运行中 Sandbox 内的 envd 服务，用于命令执行和文件操作。它只使用 Scheme + Domain （没有协议路径），并通过 X-Access-Token 携带 Runtime 令牌鉴权。这是一个 Go 客户端；完整 API 参见 Runtime 客户端，Java 绑定参见 Runtime 客户端（Java）。

package main

import (
	"context"
	"fmt"

	"github.com/openkruise/agents-api/runtime"
)

func main() {
	ctx := context.Background()

	// 集群内："sandbox-gateway.sandbox-system.svc:7788"
	// 本地调试："127.0.0.1:7788"（端口转发之后）
	domain := "sandbox-gateway.sandbox-system.svc:7788"

	// NewFromK8s 会从 Sandbox CR 注解 agents.kruise.io/runtime-access-token
	// 解析 sandboxID 和 Runtime 令牌。
	c, err := runtime.NewFromK8s(ctx, "default", "your-sandbox-name",
		runtime.WithDomain(domain),
	)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	res, _ := c.Commands.Run(ctx, "uname -a")
	fmt.Println(res.Stdout)
}

当没有 kubeconfig 访问能力时，使用 runtime.New 构建客户端，并通过 runtime.WithRuntimeToken(<token>) 显式传入令牌。

端口转发到本地调试​

端口转发将集群内的 Service 映射到 localhost，让你无需公网 DNS 和证书即可在本地工作站上迭代。

E2B / 私有协议客户端​

sandbox-gateway 会将控制面请求转发给 sandbox-manager，因此只转发 gateway Service 即可覆盖两个平面。通过 E2B_API_URL 和 E2B_SANDBOX_URL 将两个平面指向同一个本地地址（参见 使用 E2B SDK）：

export E2B_API_KEY=<your-api-key>
# 一次转发覆盖两个平面：gateway 会将管控流量转发给 sandbox-manager。
export E2B_API_URL="http://localhost:7788"
export E2B_SANDBOX_URL="http://localhost:7788"

kubectl port-forward services/sandbox-gateway 7788:7788 -n sandbox-system
from e2b import Sandbox

sbx = Sandbox.create(template="code-interpreter")
print(sbx.commands.run("echo hello").stdout)   # 数据面经由转发后的 gateway
sbx.kill()
备注

上层库 e2b-code-interpreter 和 e2b-desktop 不读取 E2B_API_URL / E2B_SANDBOX_URL，因此该本地调试配置请使用基础 e2b Sandbox。

Runtime SDK 客户端​

同一条转发同样适用；让客户端指向本地地址即可：

kubectl port-forward services/sandbox-gateway 7788:7788 -n sandbox-system
c, _ := runtime.NewFromK8s(ctx, "default", "your-sandbox-name",
	runtime.WithDomain("127.0.0.1:7788"),
	runtime.WithScheme("http"),
)

相关文档​