官网 · 文档 · DeepWiki · 快速入门 · 示例 · 路线图

agent-sandbox 能够轻松管理隔离的、有状态的单例工作负载，非常适合 AI 代理运行时等用例。

本项目正在 Kubernetes 社区的 SIG Apps 框架下开发一个名为 Sandbox 的自定义资源定义（CRD）及其控制器。其目标是提供一种声明式的标准化 API，用于管理那些需要具备长期运行、有状态、单一实例且身份稳定的容器特性的工作负载，类似于基于 Kubernetes 原语构建的轻量级单容器 VM 体验。

概述

核心：Sandbox

Sandbox CRD 是 agent-sandbox 的核心组件。它提供了一个声明式的 API 来管理具有稳定身份和持久化存储的单个有状态 Pod。这对于不适合 Deployment 的无状态复制模型或 StatefulSet 的编号稳定模型的工作负载非常有用。

Sandbox CRD 的关键特性包括：

• 稳定的身份： 每个 Sandbox 都有一个稳定的主机名和网络身份。
• 持久化存储： Sandbox 可以配置为在重启后仍能保留数据的持久化存储。
• 生命周期管理： Sandbox 控制器会管理 Pod 的生命周期，包括创建、定时删除、暂停和恢复等操作。

扩展功能

extensions 模块提供了额外的 CRD 和控制器，它们基于核心的 Sandbox API 构建，以实现更高级的功能。

• SandboxTemplate：提供了一种定义可重用模板的方式来创建 Sandbox，从而更容易管理大量相似的 Sandbox。
• SandboxClaim：允许用户从模板创建 Sandbox，隐藏了底层 Sandbox 配置的细节。
• SandboxWarmPool：管理一个预热好的 Sandbox Pod 池，可以快速分配给用户，从而减少启动新 Sandbox 所需的时间。

架构

agent-sandbox 遵循 Kubernetes 控制器模式。用户创建一个 Sandbox 自定义资源，而控制器则负责管理底层的运行时资源。

架构图

flowchart TB

    User[用户]

    Claim[SandboxClaim]
    Template[SandboxTemplate]
    Sandbox[Sandbox]

    ClaimController[Claim 控制器]
    Controller[Sandbox 控制器]

    Pod[Sandbox Pod]
    Runtime[Sandbox 运行环境]

    WarmPool[SandboxWarmPool]

    %% 用户路径
    User -->|创建| Sandbox
    User -->|创建| Claim

    %% Claim 工作流程
    Claim -->|引用| Template
    Claim -->|由| ClaimController |协调|
    ClaimController -->|创建| Sandbox

    %% Pod 处理
    ClaimController -->|从| WarmPool |接管 Pod|
    Sandbox -->|由| Controller |协调|
    Controller -->|必要时创建 Pod| Pod

    %% 运行环境
    Pod --> Runtime

    %% 温池
    WarmPool -->|预热的 Pod| Pod

安装

核心组件与扩展功能

您可以通过以下命令安装 agent-sandbox 控制器及其 CRD。

# 将 "vX.Y.Z" 替换为具体的版本标签（例如 "v0.1.0"），请参考
# https://github.com/kubernetes-sigs/agent-sandbox/releases
export VERSION="vX.Y.Z"

# 如果仅安装核心组件：
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml

# 如果安装扩展组件：
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml

Python SDK

要以编程方式与 agent-sandbox 交互，您可以使用 Python SDK。该客户端库提供了一个高层次的接口来创建和管理 Sandbox。

有关详细的安装和使用说明，请参阅 Python SDK README。

配置

对于高级的规模和并发性调优（例如 API QPS 和工作线程数量），请参阅 配置指南。

快速入门

安装完控制器后，您可以通过将以下 YAML 应用到集群来创建一个简单的 Sandbox：

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: my-sandbox
spec:
  podTemplate:
    spec:
      containers:
      - name: my-container
        image: <IMAGE>

这将创建一个名为 my-sandbox 的新 Sandbox，并运行您指定的镜像。之后，您可以通过其稳定的主机名 my-sandbox 访问该 Sandbox。

有关更复杂的示例，包括如何使用扩展功能，请参阅 examples/ 和 extensions/examples/ 目录。

动机

Kubernetes 非常擅长管理无状态的复制应用（Deployments）以及有状态且编号稳定的 Pod 集合（StatefulSets）。然而，目前越来越需要一种抽象层来处理以下场景：

• 开发环境： 为开发者提供的隔离、持久化且可通过网络访问的云环境。
• AI 代理运行时： 用于执行不受信任的、由大语言模型生成代码的隔离环境。
• Notebook 和科研工具： 适用于 Jupyter Notebook 等工具的持久化单容器会话。
• 有状态的单 Pod 服务： 托管需要稳定身份但又不想使用 StatefulSet 开销的单实例应用（如构建代理、小型数据库等）。

虽然这些场景可以通过结合 StatefulSet（大小为 1）、Service 和 PersistentVolumeClaim 来近似实现，但这种方法既繁琐又缺乏专门的生命周期管理功能，比如休眠功能。

期望的沙箱特性

我们希望沙箱能够实现厂商无关性，支持多种运行时。关键特性包括：

• 强隔离性： 支持 gVisor 或 Kata Containers 等不同运行时，以在沙箱与宿主机之间提供更强的安全性和隔离能力，包括内核隔离和网络隔离。这对于运行不可信代码或多租户场景至关重要。
• 深度休眠： 将状态保存到持久化存储，并可能对沙箱对象进行归档。
• 自动恢复： 在网络连接恢复时自动重启沙箱。
• 高效持久化： 弹性且可快速供应的存储。
• 跨沙箱内存共享： 探索在同一主机上跨沙箱共享内存的可能性，即使这些沙箱主要是异构的。这一能力取决于具体的运行时实现，用户应根据自身的安全和性能需求选择合适的运行时。
• 丰富的身份与连通性： 探索用户与沙箱的双重身份机制，以及无需为每个沙箱单独创建 Service 的高效流量路由。
• 可编程性： 鼓励应用程序和代理程序以编程方式调用沙箱 API。

路线图

当前的路线图可以在 roadmap.md 中找到。

社区、讨论、贡献与支持

这是一项由社区驱动的工作，我们欢迎各方合作！

关于 PR 处理速度的说明： 为了保持高效的处理速度并维持清晰的待处理队列，本项目采用过期 PR 管理机制（30 天自动标记为过期，15 天后自动关闭不活跃的 PR），同时允许维护者快速推进或接管已获批准的社区 PR。请阅读我们的 贡献指南，了解完整的代码审查和 PR 处理政策。

AI 辅助代码审查（实验性）

为提升代码审查效率，我们目前正在尝试使用 AI 辅助代码审查，首先采用 GitHub Copilot 作为自动化的一轮审查工具。

我们非常欢迎您对这些自动化审查的质量、相关性和帮助性的反馈！随着流程的迭代优化，我们也计划评估和测试不同的 AI 审查工具，以找到最适合我们项目工作流的方案。

⚠️ 重要贡献提示： 如果您的 PR 中收到了 Copilot 的代码建议，请务必仔细阅读我们的 贡献指南，了解如何正确应用这些建议。直接通过 GitHub UI 提交建议将违反 Kubernetes CLA 的要求。

联系我们

有关如何参与 Kubernetes 社区的信息，请访问 社区页面。

您可以联系该项目的维护者：

• Slack
• 邮件列表

欢迎您随时提交问题、提出功能建议或贡献代码！

行为准则

参与 Kubernetes 社区需遵守 Kubernetes 行为准则。

Agent Sandbox 快速上手指南

Agent Sandbox 是一个基于 Kubernetes 的开源项目，旨在轻松管理隔离的、有状态的、单实例工作负载。它特别适用于 AI Agent 运行时、开发环境、Notebook 会话等场景，提供了比 StatefulSet 更轻量且具备稳定身份和持久化存储的抽象。

环境准备

在开始之前，请确保满足以下前置条件：

• Kubernetes 集群：拥有一个可访问的 Kubernetes 集群（版本建议 1.25+）。
• kubectl 工具：已安装并配置好 kubectl，能够正常与集群通信。
• 权限要求：当前用户需具备创建自定义资源定义（CRD）和控制器的集群管理员权限。
• 网络访问：节点需能访问 GitHub Releases 以下载部署清单（若在国内访问受限，建议配置代理或自行下载 manifest 文件上传至内部仓库）。

安装步骤

你可以通过 kubectl 直接应用官方发布的 YAML 文件来安装核心组件及扩展功能。

1. 设置版本号 请将 <VERSION> 替换为 GitHub Releases 中的最新稳定版本号（例如 v0.1.0）。

   export VERSION="<VERSION>"
   

2. 安装核心组件 部署核心的 Sandbox CRD 和控制器：

   kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml
   

3. 安装扩展组件（可选） 如果需要高级功能（如模板复用 SandboxTemplate、快速分配 SandboxClaim、预热池 SandboxWarmPool），请执行：

   kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml
   

4. 验证安装 确认 CRD 已成功注册：

   kubectl get crd | grep sandbox
   # 应看到 agents.x-k8s.io/sandboxes 等资源
   

基本使用

安装完成后，你可以创建一个最简单的 Sandbox 实例。以下示例将启动一个包含指定镜像的单容器 Pod，并赋予其稳定的主机名和网络身份。

1. 创建 Sandbox 资源 将以下内容保存为 my-sandbox.yaml，并将 <IMAGE> 替换为你想要运行的容器镜像地址（例如 nginx:latest 或你的 AI Agent 镜像）：

   apiVersion: agents.x-k8s.io/v1alpha1
   kind: Sandbox
   metadata:
     name: my-sandbox
   spec:
     podTemplate:
       spec:
         containers:
         - name: my-container
           image: <IMAGE>
   

   应用配置：

   kubectl apply -f my-sandbox.yaml
   

2. 查看状态 检查 Sandbox 是否运行正常：

   kubectl get sandbox my-sandbox
   

3. 访问 Sandbox Agent Sandbox 的核心特性是提供稳定的身份。创建成功后，你可以在集群内部通过稳定的主机名 my-sandbox 直接访问该服务，无需额外创建 Service 资源。

   • 集群内访问示例：其他 Pod 可通过 my-sandbox.<namespace>.svc.cluster.local 解析并连接。
   • 持久化：即使底层 Pod 重启，该主机名和关联的存储（若配置）也将保持不变。

提示：对于更复杂的场景（如使用模板批量创建、预热池加速启动），请参考项目仓库中的 examples/ 和 extensions/examples/ 目录。