xiaods/k8e

什么是 K8E？

K8E（发音为 k-eight-e）是一个开源的 AI 代理沙箱平台。它封装了在隔离容器或微型虚拟机中运行由自主代理（Claude Code、Codex、Pi 等）生成的不可信代码所需的一切。整个系统以 小于 100 MB 的单个二进制文件 形式交付，可以将任何 Linux 主机转变为安全的、多租户的执行矩阵。

核心理念

代理隔离 – 每个 AI 驱动的工作负载都在其自己的沙箱（gVisor、Kata Containers 或 Firecracker）中运行，并具有严格的 CPU/内存限制。
代理间零信任 – 网络策略、eBPF 强制执行的出口规则以及按会话划分的工作区可防止一个代理影响另一个代理。
快速启动 – 通过预启动 Pod 的 预热池，可以在 500 毫秒内获取新会话。
兼容 E2B 的 API – 网关公开了一个与 Elastic Engine for Bots (E2B) API 匹配的 gRPC/mTLS 端点，因此现有的 LLM 代理工具包无需更改即可与其通信。
一键安装 – 一个微小的安装脚本 (curl … | sh -) 可在约 60 秒内设置好二进制文件、最小化的 Kubernetes 风格控制平面和沙箱运行时。

架构概览

AI Agent (Claude Code / Codex / Pi) ──► k8e-sandbox-cli (gRPC over mTLS)
                                            │
                                            ▼
                                   Sandbox Gateway (E2B-compatible)
                                            │
               ┌────────────────────────────┼─────────────────────────────┐
               │                            │                             │
        Session manager                Metrics & Events               Warm-pool
               │                            │                             │
               ▼                            ▼                            ▼
   ┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
   │ Sandbox pod (gVisor│   │ Sandbox pod (Kata   │   │ Pre-booted pod ready│
   │ / Kata / Firecracker)│   │ / Firecracker)      │   │ to be claimed        │
   └─────────────────────┘   └─────────────────────┘   └─────────────────────┘

Sandbox Gateway – 处理会话生命周期、文件 I/O、PTY 终端、命令执行、快照和暴露服务的单个 gRPC 服务器。
隔离运行时 – 可插拔的 RuntimeClasses：gVisor（用户空间内核，约 10 毫秒启动）、Kata Containers（基于 VM，约 500 毫秒）、Firecracker（微型 VM，约 125 毫秒）。
Cilium – 默认的 CNI 提供 eBPF 强制执行的 NetworkPolicy 和按会话的出口白名单。
预热池控制器 – 保持可配置数量的预启动沙箱 Pod，以便新会话在 < 500 毫秒内启动。

主要组件

组件	功能
Sandbox Gateway	gRPC + mTLS 入口点；实现与 E2B 兼容的会话、执行、文件、PTY、快照和指标 API。
隔离运行时	gVisor、Kata Containers、Firecracker – 通过 `RuntimeClass` 在 Pod 创建时选择。
Cilium (eBPF)	强制执行 Kubernetes `NetworkPolicy` 和按会话出口 (`allowed_hosts`)。
预热池控制器	维护一组就绪的沙箱 Pod；根据需求自动扩展。
k8e-sandbox-cli	代理用于创建会话、运行代码、读写文件和管理快照的独立客户端 (~44 MB)。
API-key 服务	为代理生成短期密钥；密钥用于 mTLS 身份验证。

入门指南（快速启动）

# 1. 安装沙箱运行时 – gVisor 是默认设置，不需要 KVM。
ARCH=$(uname -m)
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
chmod +x runsc containerd-shim-runsc-v1
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin/

# 2. 安装 K8E (单个二进制文件, <100 MB)
curl -sfL https://k8e.sh/install.sh | sh -

# 3. 验证服务
k8e-sandbox-cli status
k8e-sandbox-cli run 'echo hello from the sandbox'

安装脚本会设置一个最小化的控制平面，启动网关，并创建一个沙箱 Pod 预热池。

从 AI 代理使用沙箱

在服务器上创建 API 密钥：

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

下载适用于您操作系统的客户端 (≈44 MB) 并使其可执行。

连接 (将 /k8e-sandbox 技能安装到代理中)：

./k8e-sandbox-cli --endpoint <host>:50051 \
    --apikey k8e-abc123... connect

运行代码 – 代理现在可以发出如下命令：
```
k8e-sandbox-cli run "print('hello')" --lang python
```
CLI 会自动创建一个会话，将命令流式传输到隔离的 Pod 中，并返回输出。

README 中列出的支持代理包括 Claude Code、Codex 和 Pi。

AI 代理工作负载的关键特性

安全隔离 – 在轻量级 (gVisor) 和更强的基于 VM 的运行时之间进行选择。
资源配额 – 按会话的 CPU/内存上限，以避免失控成本。
临时工作区 – 每个会话都会获得一个自动清理的新文件系统。
内容寻址快照 – 通过 SHA-256 CAS 层存储实现快速增量恢复。
执行记录与日志 – 可恢复的命令日志，用于调试。
可观测性 – Prometheus 指标和 NDJSON 事件流。
子代理重用 – 子代理可以共享父 Pod 的工作区，同时保持隔离。
CLI 目录 – 用于 SDK 生成的机器可读命令描述。

何时使用 K8E

您正在构建 自主 AI 代理，它们可以即时生成和执行代码。
您需要 强大的隔离性（防止恶意或有缺陷的代理代码影响主机或其他代理）。
您需要 快速、按需执行，而无需每次都配置完整的虚拟机。
您更喜欢 自托管的、单个二进制文件的解决方案，而不是大型云托管服务。

许可证与社区

许可证： Apache 2.0
星标/发布： 积极维护，带有版本发布；提供适用于 x86_64、ARM64 和 RISC-V 的二进制文件。
欢迎通过常规的 GitHub 拉取请求工作流进行贡献。

总结

K8E 是一个紧凑的、自托管的沙箱矩阵，让您可以安全地大规模运行不可信的 AI 代理代码。安装一个运行时（gVisor 最简单），运行一行安装程序，创建 API 密钥，并使用 k8e-sandbox-cli 二进制文件，让您的 LLM 代理在具有亚秒级启动、严格资源限制和内置可观测性的隔离 Pod 中执行代码。