AI 智能体沙箱 xiaods/k8e

k8e.sh — 开源智能体 AI 沙箱矩阵。单二进制文件不到 100MB，把任意 Linux 主机变成安全、隔离的 AI 智能体执行平台 —— 支持 gVisor、Kata 或 Firecracker 隔离，预热池快速启动，兼容 E2B 的 API。60 秒即可跑起来。

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

🤖 K8E 是什么？

K8E 是开源智能体 AI 沙箱矩阵 —— 一个自托管的沙箱平台，用来大规模运行安全、隔离的 AI 智能体负载，打包成单二进制文件，不到 100MB。

自主 AI 智能体越来越多地生成并执行不可信代码，健壮的沙箱基础设施不再是可选项。K8E 自带所需的一切，60 秒内就能拉起生产级集群，并提供智能体隔离、资源治理、持久执行环境等一等公民原语 —— 专为 AI 时代打造。

🔒 一个集群。多个智能体。彼此零信任。

沙箱能力

| 能力 | 说明 |
| 🔒 硬件隔离 | 可插拔运行时：gVisor（默认）、Kata Containers、Firecracker microVM |
| 🌐 网络策略 | 内置 Cilium，默认执行标准 networking.k8s.io/v1 NetworkPolicy API —— 另按会话提供 eBPF toFQDNs 出站控制；allowed_hosts 通过 --cilium-dns-proxy 生效（KIP-16 M10） |
| ⚖️ 资源配额 | 按智能体会话限制 CPU/内存，防止成本失控 |
| 💾 持久工作区 | 每个会话都带 PVC 工作区（默认 1Gi local-path）；预热 Pod 启动时已预置好对应声明 —— 启动快，文件也持久 |
| 🧠 预热池 | 预启动沙箱 Pod，会话认领延迟低于 500ms；应用层就绪握手、自适应扩缩容、按会话限制后台运行数 |
| 📸 内容寻址快照 | SHA-256 CAS 层存储，zstd 压缩，分块多层清单，增量 --base 恢复，服务端仓库，自动压缩（KIP-16 M2） |
| 📜 Exec 记录 | 命令记录落盘保存，支持窗口化与偏移续读 — k8e-sandbox-cli log（KIP-16 M4） |
| 📊 可观测性 | Prometheus 指标、仅落盘的 NDJSON 事件流、进程拓扑 — events / ps 命令行（KIP-16 M5） |
| 🔄 子代理复用 | 子代理共享父 pod 与工作区；重置时相互隔离（KIP-16 M1） |
| 🧾 命令行目录 | 机器可读的命令与参数清单，供 SDK 生成使用 — catalog（KIP-16 M9） |
| 🤝 兼容 agent-sandbox | 可与 kubernetes-sigs/agent-sandbox 配合使用 |
| 🔄 SKILL + CLI + MCP | AI 智能体（Claude Code、Codex、Pi）通过 k8e-sandbox-cli 或 /k8e-sandbox 技能接入 |

📚 完整文档：k8e.sh/guide — 指南、命令行参考与示例都在官网。

🏗️ 架构

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 + PVC │ │ │ └───────────────────────┘ └────────────────┘ eBPF per-session network policy between all of them

所有操作都走同一个网关：会话生命周期、流式 exec、文件系统、PTY 终端、服务暴露（expose）、实时出站策略（allow-hosts）、内容寻址快照。智能体只需面对一扇可审计的门，不必直接接触底层基础设施。

🚀 快速开始

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

推荐 gVisor — 不需要 KVM：

ARCH=$(uname -m) # x86_64 on most servers, aarch64 on ARM
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 # must print OK
sudo tar --zstd -xf gvisor.tar.zstd -C /usr/local/bin

K8E 启动时会检测 runsc，并自动把 gVisor 配置段注入自己的 containerd 配置。不要执行 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'
第 4 步 — 连接你的 AI 智能体

下载独立沙箱命令行，完成认证，再把 /k8e-sandbox 技能装进你的智能体： bash

1. Download (~44MB) — pick your platform suffix

k8e-sandbox-cli-linux-amd64 / linux-arm64 / 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. Create an API key on the server (default TTL 30 days; --ttl never for non-expiring)

k8e sandbox-apikey create my-agent

→ {"name":"my-agent","key":"k8e-abc123...","ttl_days":30,"expires_at":"..."}

3. Connect: mTLS auth + install the skill into Claude Code / Codex / Pi

./k8e-sandbox-cli-linux-amd64 --endpoint <server-ip>:50051 --apikey k8e-abc123... connect

然后直接用日常说法让智能体干活：

「在沙箱里跑这段 Python 代码」

智能体会自动执行 k8e-sandbox-cli run，不需要你管会话。

📖 教程演示、完整命令参考和配置细节，都在官方文档站的 Sandbox CLI 指南和 Sandbox 示例里。

🆚 K8E 与其他沙箱平台对比

| | K8E 🚀 | E2B | Daytona | agent-sandbox | 自建 gVisor/Firecracker |
| 自托管、单二进制 | ✅ <100MB | ⚠️ 重（每个环境一套 VM 镜像） | ✅ | ❌ 需要 K8s 集群 | ❌ 自己搭 |
| 隔离运行时 | ✅ gVisor / Kata / Firecracker — 可插拔 | Firecracker microVM | ✅ microVM/容器 | K8s RuntimeClass | 单一运行时 |
| E2B SDK 兼容 | ✅ 原生（官方 SDK 不用改） | ✅ 原生 | ❌ 自有 API | ❌ | ❌ |
| 预热池（500ms 内领取） | ✅ 内置，自适应扩缩 | ✅ 托管 | ⚠️ | ⚠️ 手动扩缩 | ❌ |
| 按会话的网络策略（eBPF） | ✅ Cilium，可实时配置 | 托管（固定） | ⚠️ | ⚠️ NetworkPolicy | 手写 |
| 协议 | Apache 2.0 | Apache 2.0（托管核心收费） | Apache 2.0 | Apache 2.0 | — |

什么时候选 K8E： 你想要 E2B 风格的沙箱，但要自托管，而且工具面比「跑代码」更宽——PTY 终端、快照、服务暴露、实时出站策略，全部走同一个可审计网关。

🤝 参与贡献 bash
git clone https://github.com/<your-username>/k8e.git && cd k8e
git checkout -b feat/my-feature
make && make test
git push origin feat/my-feature

- 🐛 报告 Bug
- 💡 功能建议
- 🔍 查看 PR

🛡️ 安全

漏洞请通过 GitHub Security Advisories 上报。安全类问题不要开公开 issue。

📄 协议

Apache License 2.0 — 见 LICENSE。

🙏 致谢

| 项目 | 贡献 |
| 🐄 K3s | 轻量级 Kubernetes 基础，启发了 K8E |
| ☸️ Kubernetes | 一切构建于其上的编排引擎 |
| 🔷 Cilium | 基于 eBPF 的网络与按会话的出站控制 |
| 🤖 agent-sandbox | Kubernetes 原生的智能体沙箱基础组件 |
| 🌐 CNCF | 培育开源云原生生态 |

k8e.sh — 开源智能体 AI 沙箱矩阵

如果 K8E 为你的智能体提供动力，给我们点个 ⭐ —— 这对我们意义重大！