AI 智能体沙箱xiaods/k8e

Go Version
License
Stars
Release
Arch

k8e.sh — 开源智能体 AI 沙箱矩阵。一个 小于 100MB 的单一二进制文件，可将任何 Linux 主机转变为安全、隔离的 AI 智能体执行平台——支持 gVisor、Kata 或 Firecracker 隔离、热池快速启动，以及兼容 E2B 的 API。60 秒内即可启动并运行。

curl -sfL https://k8e.sh/install.sh | sh -
就这样。你的智能体沙箱矩阵已准备就绪。🤖

📖 目录

| # | 章节 |
|---|---------|
| 1 | 🤖 什么是 K8E？ |
| 2 | 🏗️ 架构 |
| 3 | ⚙️ 组件 |
| 4 | 🚀 快速开始 |
| 5 | 🔒 沙箱运行时设置 |
| 6 | 🤖 沙箱 CLI |
| 7 | 🖥️ 高级安装 |
| 8 | 🆚 K8E 与其他沙箱平台对比 |
| 9 | 🤝 贡献 |
| 10 | 🙏 致谢 |

🤖 什么是 K8E？

K8E 是 开源智能体 AI 沙箱矩阵——一个自托管的沙箱平台，用于大规模运行安全、隔离的 AI 智能体工作负载，并以小于 100MB 的单一二进制文件形式打包。
随着自主 AI 代理越来越多地生成并执行不受信任的代码，健壮的沙箱基础设施不再是可选项。K8E 提供了在 60 秒内启动生产级集群所需的一切，并内置了用于代理隔离、资源治理和临时执行环境的一流原语——专为 AI 时代打造。

🔒 一个集群。多个代理。彼此之间零信任。

沙箱能力

| 能力 | 描述 |
|---|---|
| 🔒 硬件隔离 | 可插拔运行时：gVisor（默认）、Kata Containers、Firecracker microVM |
| 🌐 网络策略 | Cilium eBPF toFQDNs 出口控制——按会话生效，无需代理进程；通过 --cilium-dns-proxy 强制执行 allowed_hosts（KIP-16 M10） |
| ⚖️ 资源配额 | 按代理会话限制 CPU/内存上限，防止成本失控 |
| 🗑️ 临时工作区 | 代理会话结束后自动清理；为子代理提供按会话隔离的工作区（KIP-16 M1） |
| 🧠 预热池 | 预启动的沙箱 Pod，实现低于 500ms 的会话获取延迟；应用层就绪握手、自适应扩缩容、按会话的后台运行上限 |
| 📸 内容寻址快照 | SHA-256 CAS 层存储，采用 zstd 压缩、分块多层清单、增量 --base 恢复、服务端注册表、自动压缩（KIP-16 M2） |
| 📜 执行记录 | 基于文件、窗口化、可偏移续传的命令记录——k8e-sandbox-cli log（KIP-16 M4） |
| 📊 可观测性 | Prometheus 指标、仅磁盘的 NDJSON 事件流、进程拓扑——events / ps CLI（KIP-16 M5） |
| 🔄 子代理复用 | 子代理共享父 Pod + 工作区；隔离重置（KIP-16 M1） |
| 🧾 CLI 目录 | 用于 SDK 生成的机器可读命令/标志接口——catalog（KIP-16 M9） |
| 🤝 兼容 agent-sandbox | 可与 kubernetes-sigs/agent-sandbox 配合使用 |
| 🔄 SKILL + CLI | AI 代理（claude code、codex、pi）通过 k8e-sandbox-cli CLI 命令连接 |

🏗️ 架构

AI Agents (Claude Code / Codex / Pi / dsh)
│  k8e-sandbox-cli / plugin tools    (gRPC over mTLS)
▼
┌──────────────────────────────────────────────┐
│              SANDBOX GATEWAY                 │
│  sessions · exec · files · PTY terminals     │
│  expose · allow-hosts · snapshots            │
│  warm pool · metrics · event stream          │
└──────────────┬───────────────────────────────┘
│ claims ready pods from the warm pool
┌───────────▼───────────┐   ┌────────────────┐
│   SANDBOX POD         │   │   SANDBOX POD  │
│   gVisor / Kata / FC  │ … │   (isolated)   │
│   agent's code + fs   │   │                │
└───────────────────────┘   └────────────────┘
eBPF per-session network policy between all of them

一个网关统一承载所有操作——会话生命周期、流式执行、
文件系统、PTY 终端、服务暴露（expose）、实时出站策略
（allow-hosts）以及内容寻址快照——因此智能体获得一扇经过审计的
门，而不是原始的基础设施访问权限。

⚙️ 组件

| 组件 | 用途 |
|---|---|
| 🚪 Sandbox Gateway | 单一 gRPC（mTLS）+ 兼容 E2B 的 HTTP 入口：会话、exec、文件、PTY 终端、暴露、快照 |
| 🛡️ gVisor / Kata / Firecracker | 可插拔的沙箱隔离运行时（用户空间内核 / 轻量级虚拟机 / 微虚拟机） |
| 🔷 Cilium (eBPF) | 按会话的网络策略与出站控制——无需代理进程 |
| 🧠 Warm Pool Controller | 预启动的沙箱 Pod、自适应扩缩容、亚 500ms 的申领 |
| 🤖 k8e-sandbox-cli | 独立智能体 CLI——连接、运行、暴露、快照（catalog 用于 SDK 生成） |
| 🔌 dsh 插件系列 | @k8e-sandbox/ npm 包——与模型表面工具集成的 DeepSeek Harness |

🚀 快速开始

步骤 1 — 安装沙箱运行时（建议：在 K8E 之前）

在 K8E 之前安装运行时 shim，以便在首次启动时自动检测到它。推荐使用 gVisor——无需 KVM。

直接从 gVisor 发布存储桶下载 runsc + containerd-shim-runsc-v1（需要 wget）
ARCH=$(uname -m)   # 大多数服务器上为 x86_64，ARM 上为 aarch64
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}

wget ${URL}/runsc ${URL}/runsc.sha512 \
${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512

sha512sum -c runsc.sha512 -c containerd-shim-runsc-v1.sha512   # 两者都必须打印 OK
chmod +x runsc containerd-shim-runsc-v1
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin/
ls -l /usr/local/bin/runsc /usr/local/bin/containerd-shim-runsc-v1   # 验证两者均已安装

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

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

步骤 2 — 安装 K8E

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

步骤 3 — 验证沙箱

k8e-sandbox-cli status        # -> {"available": true, ...}
k8e-sandbox-cli run 'echo hello from the sandbox'

（可选，使用 KUBECONFIG=/etc/k8e/k8e.yaml：kubectl -n sandbox-matrix get pods 显示预热池 Pod。）

步骤 4 — 下载沙箱 CLI 并连接你的 AI 智能体

下载独立的沙箱 CLI，进行身份验证，并将技能安装到你的智能体中：

下载沙箱 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

在服务器上创建 API 密钥（默认 TTL 30 天；使用 --ttl never 表示永不过期）
k8e sandbox-apikey create my-agent
→ {"name":"my-agent","key":"k8e-abc123...","ttl_days":30,"expires_at":"..."}

连接：认证（mTLS）+ 将 /k8e-sandbox 技能安装到 agent harnesses 中
./k8e-sandbox-cli --endpoint :50051 --apikey k8e-abc123... connect

可选的多集群配置文件（~/.k8e/sandbox/profiles.yaml — 不是服务器上的 /etc/k8e/config.yaml）
参见 docs/kip-17-sandbox-cli-profiles-and-apikey-ttl.md
./k8e-sandbox-cli --profile prod connect --apikey k8e-...

本地使用： 如果你与 K8E 服务器在同一台机器上，CLI 会自动发现 TLS 证书——只需运行 k8e-sandbox-cli connect。

平台二进制文件：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 创建符号链接）

一个二进制文件，两个名称： 下载的 k8e-sandbox-cli-linux-amd64 文件就是该技能所使用的 k8e-sandbox-cli 命令。connect 会将其符号链接到 ~/.local/bin/k8e-sandbox-cli（位于 PATH 中），并将 /k8e-sandbox 技能安装到你的 agent harnesses 中，因此每个技能示例（k8e-sandbox-cli run ...）使用的都是你刚刚下载的同一个文件。

然后自然地询问你的 agent：

“在沙箱中运行这段 Python 代码片段”

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

支持的 agent：claude code、codex、pi。

🔒 沙箱运行时设置

K8E 会自动检测已安装的运行时并注册相应的 RuntimeClass。根据你的隔离需求进行选择：

| 运行时 | 隔离 | 要求 | 启动时间 |
|---|---|---|---|
| gVisor | 系统调用拦截（用户空间内核） | 无 | ~10ms |
| Kata Containers | VM 支持（QEMU） | 嵌套虚拟化或裸金属 | ~500ms |
| Firecracker | 硬件 microVM（KVM） | /dev/kvm | ~125ms |

gVisor — 推荐的默认选项
bash
直接从 gVisor 发布存储桶下载 runsc + containerd-shim-runsc-v1（需要 wget）
ARCH=$(uname -m)   # 大多数服务器上为 x86_64，ARM 上为 aarch64
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}

wget ${URL}/runsc ${URL}/runsc.sha512 \
${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512

sha512sum -c runsc.sha512 -c containerd-shim-runsc-v1.sha512   # 两者都必须输出 OK
chmod +x runsc containerd-shim-runsc-v1
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin/
ls -l /usr/local/bin/runsc /usr/local/bin/containerd-shim-runsc-v1   # 验证两者均已安装

不要运行 runsc install——K8E 在 /var/lib/k8e/agent/etc/containerd/config.toml 管理自己的 containerd 配置，并在启动时自动注入 gVisor 配置段。

Kata Containers
bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/kata-containers/kata-containers/main/utils/kata-manager.sh) install-packages"
kata-runtime check

Firecracker（需要 /dev/kvm）

ls /dev/kvm   # 验证 KVM 是否可用

安装 firecracker-containerd shim + devmapper snapshotter
参见：https://github.com/firecracker-microvm/firecracker-containerd
mkdir -p /var/lib/firecracker-containerd/runtime
将 hello-vmlinux.bin 和 default-rootfs.img 放在此处

应用更改

在启动 K8E 之前安装运行时，以实现零重启配置。如果 K8E 已在运行，则在安装新的运行时 shim 后重启它：

systemctl restart k8e
kubectl get runtimeclass
NAME          HANDLER       AGE
gvisor        runsc         10s
kata          kata-qemu     10s
firecracker   firecracker   10s   ← 仅在存在 /dev/kvm 时

🤖 沙箱 CLI

k8e-sandbox-cli 是一个独立的二进制文件（约 44MB），让 AI 代理可以直接访问 K8E 沙箱基础设施——无需安装服务器。

AI Agent (claude code / codex / pi)
│  shell command
▼
k8e-sandbox-cli run "print('hello')" --lang python
│  gRPC (TLS)
▼
sandbox-grpc-gateway:50051
│
▼
Isolated Pod (gVisor / Kata / Firecracker)

安装 Skill

在服务器上，创建一个 API 密钥以实现安全的远程访问：

k8e sandbox-apikey create my-agent
→ {"name":"my-agent","key":"k8e-abc123..."}

在客户端上，下载独立的 CLI，登录，并安装 skill：

1. 下载特定平台的二进制文件（约 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

2. 将纯命令名符号链接到下载的文件（不要重命名）
ln -s k8e-sandbox-cli-linux-amd64 k8e-sandbox-cli

3. 连接：mTLS 认证 + 将 /k8e-sandbox skill 安装到 Claude/Codex/Pi
注意：--endpoint 和 --apikey 是全局标志，放在子命令之前
./k8e-sandbox-cli --endpoint :50051 --apikey k8e-abc123... connect

平台二进制文件：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 创建符号链接）

一个二进制文件，两个名称： 下载的 k8e-sandbox-cli-linux-amd64 文件就是 skill 所使用的 k8e-sandbox-cli 命令——符号链接只是指向同一文件的纯名称别名。connect 会安装 /k8e-sandbox skill，因此每个 skill 示例（k8e-sandbox-cli run ...）都是你刚刚下载的同一个文件。

然后在你的代理框架中：

/k8e-sandbox

或者自然地提问：“在沙箱中运行这段 Python 代码片段”——该 skill 会驱动 k8e-sandbox-cli run。

可用命令

| 命令 | 描述 |
|---|---|
| k8e-sandbox-cli --profile  … | 使用 ~/.k8e/sandbox/profiles.yaml 中的命名配置文件（KIP-17；不是 /etc/k8e/config.yaml） |
| k8e-sandbox-cli connect | 连接本地/远程网关并安装 /k8e-sandbox agent 技能 |
| k8e-sandbox-cli connect --skill-only | 仅重新安装 agent 技能（不拨号网关） |
| k8e-sandbox-cli login | 仅进行身份验证（mTLS 证书；不安装技能） |
| k8e-sandbox-cli run  | 运行代码或 shell 命令（自动创建/管理会话） |
| k8e-sandbox-cli status | 检查沙箱服务可用性和当前会话 |
| k8e-sandbox-cli create | 创建新会话（自定义运行时、出口、清单、git-repo） |
| k8e-sandbox-cli destroy  | 销毁会话并释放资源 |
| k8e-sandbox-cli write   | 将文件写入 /workspace（内容通过 stdin） |
| k8e-sandbox-cli read   | 从 /workspace 读取文件 |
| k8e-sandbox-cli list  | 列出 /workspace 中的文件（按 --since 时间戳过滤） |
| k8e-sandbox-cli subagent  | 在父会话下生成子沙箱（最大深度 1） |
| k8e-sandbox-cli confirm   | 将不可逆操作交由人工批准 |
| k8e-sandbox-cli approve  | 批准待处理的确认请求 |
| k8e sandbox-apikey create  [--ttl 30d\|never] | 创建 API 密钥（默认 TTL 30 天） |
| k8e sandbox-apikey list | 列出 API 密钥名称 + 过期时间（不显示密钥） |
| k8e sandbox-apikey delete  | 删除 API 密钥（服务器端） |

参见 pkg/sandboxcli/skills/k8e-sandbox/SKILL.md 和 docs/kip-17-sandbox-cli-profiles-and-apikey-ttl.md。

快速示例

运行 Python 代码（自动创建会话）
k8e-sandbox-cli run "print('hello')" --lang python

Shell 命令（默认 lang=bash）
k8e-sandbox-cli run "ls -la /workspace"

TypeScript — 类型注解通过 tsx 运行
k8e-sandbox-cli run "const nums: number[] = [1, 2, 3]; console.log(nums.reduce((a, b) => a + b, 0))" --lang ts

通过 stdin 的多行 TypeScript（接口、async/await）
k8e-sandbox-cli run --lang ts  {
return users.reduce((a, b) => (a.age > b.age ? a : b));
}

const users: User[] = [{ name: "Ada", age: 36 }, { name: "Linus", age: 54 }];
oldest(users).then((u) => console.log(Oldest: ${u.name} (${u.age})));
EOF

通过 stdin 的多行
k8e-sandbox-cli run --lang python  \
K8E_URL=https://:6443 \
INSTALL_K8E_EXEC="agent" \
sh -

禁用 Sandbox Matrix

curl -sfL https://k8e.sh/install.sh | INSTALL_K8E_EXEC="server --disable-sandbox-matrix" sh -

关键环境变量

K8E_TOKEN=              # 集群加入令牌
K8E_URL=https://:6443   # 服务器 URL（agent 节点）
K8E_KUBECONFIG_OUTPUT=    # kubeconfig 输出路径

🆚 K8E 与其他沙箱平台对比

K8E 与面向 AI agent 的主流沙箱的对比：

| | K8E 🚀 | E2B | Daytona | agent-sandbox (k8s-sig) | DIY gVisor/Firecracker |
|---|---|---|---|---|---|
| 自托管、单一二进制文件 | ✅

何时选择 K8E

- 你想要E2B 风格的沙箱但自托管——相同的官方 SDK、你的基础设施、无按席位定价。
- 你的代理需要超越“运行代码”的丰富工具面：PTY 终端、快照、服务暴露和实时出口策略——全部通过一个经过审计的网关。
- 你想要可插拔隔离（按会话切换 gVisor ↔ Kata ↔ Firecracker），而不是被锁定在单一微虚拟机栈上。

🤝 贡献

git clone https://github.com//k8e.git && cd k8e
git checkout -b feat/my-feature
make && make test
git push origin feat/my-feature

- 🐛 Bug 报告
- 💡 功能请求
- 🔍 打开的 PR

🛡️ 安全

通过 GitHub 安全公告报告漏洞。请勿为安全漏洞打开公开 issue。

📄 许可证

Apache License 2.0 — 参见 LICENSE。

🙏 致谢

| 项目 | 贡献 |
|---|---|
| 🐄 K3s | 启发了 K8E 的轻量级 Kubernetes 基础 |
| ☸️ Kubernetes | 一切所构建于其上的编排引擎 |
| 🔷 Cilium | 由 eBPF 驱动的网络和每会话出口控制 |
| 🤖 agent-sandbox | Kubernetes 原生代理沙箱原语 |
| 🌐 CNCF | 培育开源云原生生态系统 |

k8e.sh — 开源代理式 AI 沙箱矩阵

GitHub
Website
Docs

如果 K8E 为你的代理提供支持，请给我们一个 ⭐——这对我们意义重大！*