hullwork/sandbox Vibe 项目

项目简介

hullwork/sandbox 是由独立开发者 hullwork 开源的一个 AI Agent 安全执行边界项目，每个 Runtime 以 Kubernetes 上的 gVisor Pod 形式运行，默认 non-root、只读根文件系统、无 ServiceAccount token、default-deny NetworkPolicy，实现了 Agent 执行环境与宿主机之间的严格隔离。Control Plane 或 Runtime 不可用时操作直接失败，不会降级到宿主机执行。项目采用 MIT 协议开源，定位为 AI Agent 基础设施级别的安全加固方案。

核心功能

gVisor 强隔离 Runtime

每个 Agent Shell 和文件操作均运行在独立的 gVisor Pod 中。gVisor 通过用户态内核（runsc）拦截系统调用，相比传统容器提供更细粒度的系统调用过滤。Pod 配置强制 non-root 运行、根文件系统只读、不自动挂载 ServiceAccount token，网络策略默认为拒绝（default-deny），任何出站连接均需显式声明。

多入口接入（Python SDK / CLI / MCP Bridge）

Agent 通过四种方式接入沙箱：Python SDK（sandbox_platform）、sandbox 命令行工具、sandboxctl 管理CLI，以及 stdio MCP Bridge（sandbox-mcp，提供九个 Agent 作用域的 MCP 工具）。所有接入方式均通过 HTTPS + 租户 API Key 认证，租户身份由凭证决定，而非请求体中的任意声明。

故障闭环保证

Control Plane 或 Runtime 不可达时，操作立即失败，绝不会静默降级到宿主机执行。这是该项目的核心安全契约，适用于为 AI Agent 提供代码执行能力但不希望其触及宿主机的任何场景。

Workspace 持久化与 Checkpoint

Workspace 生命周期与 Runtime 生命周期独立。停止 Runtime 不影响 Workspace PVC 中的文件保留。Checkpoints 是显式恢复路径而非默认持久化方案，支持在必要时从检查点恢复工作状态。

完整本地集群快速启动

make quickstart 一条命令在 Lima 虚拟化环境中启动完整的多节点 kubeadm 集群，验证 gVisor Runtime 冷启动延迟（p50 2.497s / p95 2.789s）、热执行延迟（p50 35.72ms / p95 48.08ms）以及安全边界是否按预期工作。

技术实现

项目使用 Python 构建完整的 Control Plane 和 Runtime 组件。Control Plane 负责准入控制、配额管理、Token 签发和 Workspace/Runtime 生命周期管理，后端支持 PostgreSQL、MySQL 或 SQLite（开发环境）。Runtime Worker Pool 以 Kubernetes RuntimeClass: gvisor 运行，配合 Cilium 网络插件和 Rook/Ceph 存储实现多节点持久化 Workspace 挂载。基准测试在 Apple Silicon + Lima 专用虚拟机环境下完成，5 轮 × 100 次迭代，结果已写入 docs/BENCHMARK_REPORT_2026-09-01.md 并附带「此数据不代表云上多租户性能」的明确声明。

快速上手

1. 确认主机环境：macOS 或 Linux、amd64 或 arm64、10.5 GiB 可用内存、Docker daemon 可达、limactl/kubectl/helm/python3/openssl 在 PATH 中；
2. 执行 make doctor 检查所有依赖项是否满足，不满足时提前终止而非运行到一半报错；
3. 执行 make bootstrap 创建 .venv 并安装 SDK 及测试依赖（Debian/Ubuntu 上强制使用虚拟环境，PEP 668 拒绝 system-wide pip）；
4. 执行 make quickstart 自动创建或复用仓库的独立 Lima 集群，验证 gVisor 内核运行状态、Runtime 无 ServiceAccount token、Workspace 文件在停止 Runtime 后保留、Control Plane 不可达时失败闭包；
5. 保持 make console-forward 运行，在浏览器打开 http://127.0.0.1:18081，使用 make dev-token 获取本地登录密钥进入 Operator Console。

适用人群

为 AI Agent 构建安全执行环境的基础设施工程师、研究 AI Agent 安全边界的研究者、需要让 AI Agent 执行 Shell 命令但不希望其访问宿主机的开发团队，以及关注开源安全工具链的企业技术团队。

官方链接

• GitHub 仓库：https://github.com/hullwork/sandbox
• 项目官网：https://hullwork.github.io/sandbox/