快速开始

学习路径（建议按此顺序阅读）

  1. 什么是 K8E —— 它是什么、为什么
  2. 本页 —— 安装并跑通第一个沙箱
  3. 沙箱运行时配置 —— gVisor/Kata/Firecracker 详解
  4. Sandbox CLI —— 全部命令，含服务暴露
  5. 沙箱范例 —— 真实 agent 驱动的实战
  6. DeepSeek Harness 接入 / E2B SDK —— 接入你的 agent
  7. 架构 与 组件 —— 内部原理

遇到问题？运行 k8e-sandbox-cli doctor 自动诊断并给出修复建议。

从零到运行中的 agentic 沙箱矩阵。

第 1 步 —— 安装 K8E

curl -sfL https://k8e.sh/install.sh | sh -

安装脚本会拉取最新版本。本指南在 v1.37.0-20261022-rc2 及更新版本上验证过—— 更早的版本缺少沙箱守护进程里的若干修复，而下面的页面依赖它们（彩色命令输出、 文件监听的事件名）。

一键安装脚本会自动安装推荐的沙箱运行时（gVisor）——无需 KVM。

可选 —— 手动安装沙箱运行时（gVisor）

建议先安装运行时 shim，以便 K8E 首次启动时自动检测。推荐 gVisor —— 无需 KVM。（以下手动步骤适用于预装、离线主机或自定义二进制位置。）

# 官方 “Latest release” 包：https://gvisor.dev/docs/user_guide/install/#latest-release
# 2026-07 起改为多文件布局，不再单独发布 runsc 二进制。
ARCH=$(uname -m)   # x86_64 最常见，ARM 为 aarch64
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}

wget ${URL}/gvisor.tar.zstd ${URL}/gvisor.tar.zstd.sha512

sha512sum -c gvisor.tar.zstd.sha512   # 必须输出 OK
sudo tar --zstd -xf gvisor.tar.zstd -C /usr/local/bin
ls -l /usr/local/bin/runsc /usr/local/bin/containerd-shim-runsc-v1 /usr/local/bin/gvisor-bin   # 确认已安装

主机没有 zstd？同一目录提供了 gvisor.tar.bz2，可改用 sudo tar -xjf gvisor.tar.bz2 -C /usr/local/bin。

压缩包含 runsc、containerd-shim-runsc-v1 shim 以及 gvisor-bin/ 侧车二进制目录（runsc 在自身二进制旁边查找）。请整体解压、保持文件在一起 —— 不要单独移动 runsc。

K8E 启动时会检测 runsc，并自动把 gVisor 配置注入其 containerd 配置（/var/lib/k8e/agent/etc/containerd/config.toml）。不要运行 runsc install —— K8E 管理自己的 containerd 配置。

需要更强的隔离？参见 沙箱运行时配置 了解 Kata Containers 和 Firecracker。

第 2 步 —— 验证集群

export KUBECONFIG=/etc/k8e/k8e.yaml
kubectl get nodes
kubectl get runtimeclass              # 应显示: gvisor
kubectl -n sandbox-matrix get pods   # Sandbox Matrix 自动启动

第 3 步 —— 把客户端连上集群

涉及两个不同的二进制，而且它们在不同的机器上：

二进制跑在哪干什么用
k8e服务器集群本体。也承载 k8e sandbox-apikey create。
k8e-sandbox-cli客户端（你的电脑）与集群对话，你的 Agent 驱动的是它。

3a —— 在服务器上：告诉服务器客户端会拨的地址，然后签发 key

客户端通过 :50051（gRPC，mTLS）访问沙箱网关。网关证书是根据主机网卡地址生成的， 在 AWS 上那就是私网 VPC IP——客户端拨公网地址会 TLS 握手失败。要告诉服务器它的公网名字：

# /etc/k8e/config.yaml  （k8e server/agent 守护进程的配置）
sandbox-advertise-hostname: 203.0.113.10     # 纯 DNS 名或纯 IP
sudo systemctl restart k8e.service

只能是纯名字或纯 IP——不带 scheme、不带端口、不带路径。重启服务，证书会自动重新生成。

然后创建 API key（默认 TTL 30 天）：

k8e sandbox-apikey create my-agent
# → {"name":"my-agent","key":"849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9",
#    "e2b_key":"e2b_849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9",
#    "ttl_days":30,"expires_at":"..."}

把输出里的两半都留好：裸 hex 的 key 是 k8e-sandbox-cli --apikey 要的， e2b_key（同样的 hex 加 e2b_ 前缀）是官方 E2B SDK 要的——它们的 validateApiKey 会在发请求前拒绝裸 hex token。

3b —— 在客户端：下载、信任 CA、连接

# 下载 sandbox CLI (~44MB) —— 选择你的平台后缀
#   k8e-sandbox-cli-linux-amd64 / linux-arm64 / darwin-amd64 / darwin-arm64 / windows-amd64.exe
curl -sLO https://github.com/xiaods/k8e/releases/latest/download/k8e-sandbox-cli-linux-amd64
chmod +x k8e-sandbox-cli-linux-amd64

# 为普通命令名创建软链接（不要重命名）
ln -s k8e-sandbox-cli-linux-amd64 k8e-sandbox-cli

网关用的是私有 CA，所以首次 connect 需要这个 CA。在服务器上导出：

# 在服务器上
sudo cat /var/lib/k8e/server/tls/sandbox-ca.crt > ~/sandbox-ca.crt

用任何你信任的通道（scp、共享卷、你的密钥库都行——它是公开证书，不是秘密）把它拷到 客户端，然后连接：

# 在客户端上
./k8e-sandbox-cli --endpoint 203.0.113.10:50051 --apikey 849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9 \
  connect --ca-file ~/sandbox-ca.crt

connect 会完成 mTLS 认证、记住这个网关、把 CLI 放进 PATH，并把 /k8e-sandbox skill 安装到你的 Agent 工具链。

和服务器在同一台机器上？ 直接运行 k8e-sandbox-cli connect —— CLI 会自动发现本地 网关及其证书，既不需要 API key 也不需要 CA。

3c —— 验证一下真的通了

一条命令就能跑通整条链路——API key、客户端证书、网关、warm pool、运行时：

k8e-sandbox-cli run 'echo hello from k8e'
# → {"…","exit_code":0,"stdout":"hello from k8e\n","status":"completed", …}

stdout 里有 hello from k8e 就说明你已经在一个隔离的 gVisor Pod 里执行代码了。 如果失败，故障排查表会把症状对应到原因。

可选：多集群 profile —— 在 ~/.k8e/sandbox/profiles.yaml，不是服务器的 /etc/k8e/config.yaml： ./k8e-sandbox-cli --profile prod connect --apikey <key>

平台二进制：k8e-sandbox-cli-{darwin,linux,windows}-{amd64,arm64}（Windows：k8e-sandbox-cli-windows-amd64.exe，通过 mklink k8e-sandbox-cli.exe k8e-sandbox-cli-windows-amd64.exe 建软链接）

同一个二进制，两个名字： 下载的带平台后缀文件就是 SKILL 中使用的 k8e-sandbox-cli 命令 —— 软链接只是普通名字的别名。connect 会安装 /k8e-sandbox skill 到你的 Agent 工具链（并可能软链到 ~/.local/bin/），因此 SKILL 里的所有示例（k8e-sandbox-cli run ...）都是你刚下载的同一个文件。

配置文件不要混用： /etc/k8e/config.yaml 只给 k8e server/agent 守护进程用；CLI 多集群 profile 在 ~/.k8e/sandbox/profiles.yaml；mTLS 证书在 ~/.k8e/sandbox/{ca.crt,client.crt,client.key}（客户端证书 90 天，剩余不足 30 天时自动续期）。

然后自然地对你的 Agent 说：

"在沙箱里运行这段 Python 代码"

Agent 会自动执行 k8e-sandbox-cli run —— 无需手动管理会话。

支持的 Agent：Claude Code、Codex、Pi。

第 4 步 —— 把已有的 E2B 应用搬过来（可选）

如果你的代码本来就说 E2B，指向同一个集群即可——不用改代码：

export E2B_API_KEY="e2b_849a5302e66f98d1d5064ef8501703574af4053b7bf9cf5337f9533326ce2bc9"   # 4a 里的 e2b_key
export E2B_API_URL="http://203.0.113.10:80"          # 集群的 Gateway，HTTP :80
export E2B_SANDBOX_URL="http://203.0.113.10:80/e2b/envd"

官方 SDK 一行不改就能对接你的集群。完整走查见 使用官方 E2B SDK 操作沙箱 —— 包括最先撞上的两件事： template 参数是 runtime class（gvisor），以及 Code Interpreter SDK 不受支持。

下一步： 上手练习请见沙箱范例 —— 从单行跑马灯到完整的 Vue 网站，全程通过 skill 由你的 Agent 驱动。

最近更新: