OpenSandbox Agent-Sandbox 实战基于 kubernetes-sigs/agent-sandbox 创建沙箱并用 Python SDK 执行命令【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本篇技术指南基于 OpenSandbox 仓库中的 agent-sandbox 示例examples/agent-sandbox/README.md 与 docs/examples/agent-sandbox.md讲解如何将 OpenSandbox Server 配置为 Kubernetes 运行时并使用agent-sandboxworkload provider创建由kubernetes-sigs/agent-sandbox的 Sandbox CRD 承载的沙箱再通过 OpenSandbox Python SDK 在其中执行命令。读完后你将掌握workload_provider agent-sandbox的完整配置方法、agent-sandbox v1beta1 API 的兼容性迁移要点以及服务端AgentSandboxProvider从创建 Sandbox CR 到状态/端点解析的源码级实现原理。示例定位一个最小闭环的 agent-sandbox 集成该示例做的事情非常聚焦使用一个由kubernetes-sigs/agent-sandbox控制的 Sandbox 资源创建沙箱而非 OpenSandbox 自有的 BatchSandbox CRD通过 OpenSandbox Python SDK 的Sandbox.create创建沙箱并调用sandbox.commands.run(echo hello world)执行一条命令验证预期输出command output: hello world随后sandbox.kill()销毁资源。它的价值在于演示了 OpenSandbox Kubernetes 运行时的多 workload provider 架构server 的 Kubernetes 运行时通过 provider 工厂注册了batchsandbox与agent-sandbox两种底层 CRD 抽象见 provider_factory.py你可以选择接入社区维护的 agent-sandbox 控制器来管理沙箱 Pod 的生命周期而 OpenSandbox 的 API、execd、ingress 等能力保持不变。前置条件按 docs/examples/agent-sandbox.md 给出的前提你需要满足以下条件一个已安装agent-sandbox v0.5.0controller 及其 CRD 的 Kubernetes 集群且提供agents.x-k8s.io/v1beta1APIOpenSandbox Server 使用 Kubernetes 运行时并配置workload_provider agent-sandbox沙箱镜像需包含bash示例默认使用ubuntu:22.04因为示例命令通过 shell 执行echo hello world。兼容性与迁移只支持 v1beta1无 v1alpha1 回退这是 agent-sandbox 集成中最容易踩坑的部分文档在 docs/examples/agent-sandbox.md 中给出了明确的迁移约束OpenSandbox 的 server provider 与 ingress informer仅使用agents.x-k8s.io/v1beta1。该 API 自 agent-sandbox v0.5.0 起可用v1.0.0 将移除v1alpha1且 OpenSandbox 侧没有 v1alpha1 回退逻辑。因此使用前必须先将集群中的 controller 与 CRD 升级到提供 v1beta1 的版本。存量集群迁移顺序先把 agent-sandbox 升级到同时提供两个版本的 release如 v0.5.0确认其 conversion webhook 健康再同时升级 OpenSandbox server 与 ingress在切换到移除 alpha API 的 agent-sandbox release 之前完成上游资源/存储迁移。自定义模板更新如果你维护自定义 AgentSandbox 模板需要改为apiVersion: agents.x-k8s.io/v1beta1并移除spec.replicas。server 会在创建新沙箱时包括合并自定义模板时自动设置spec.operatingMode: Running和spec.service: true——Service 是必需的因为 ingress 依赖status.serviceFQDN做路由下文源码部分会印证。不会改写存量资源上述字段只在创建新沙箱时应用。v0.5.0 的 alpha 到 beta 转换会保留被省略的service字段若某个存量沙箱没有 Service/FQDN需要显式对该资源启用spec.service: true并等待ReadyTrue且status.serviceFQDN填充完成即可无需重建沙箱地恢复 ingress 路由。有意保持无 Service 的资源应保持不变。语义保持配置的shutdownPolicy、pod 模板合并、以及绝对时间的shutdownTime语义均被保留。不带过期时间的请求会省略shutdownTime即使模板中提供了该值。状态与端点解析仍依赖Ready条件、selector、podIPs和serviceFQDN。注意区分OpenSandbox 自有的 BatchSandbox API 仍是sandbox.opensandbox.io/v1alpha1与 agent-sandbox 的 API 版本无关。启动 OpenSandbox Server1. 安装 server 并生成初始配置uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker2. 修改~/.sandbox.toml将 [runtime]、[kubernetes]、[agent_sandbox] 三个相关段落配置为[runtime] type kubernetes execd_image opensandbox/execd:v1.1.0 [kubernetes] namespace default # kubeconfig_path /absolute/path/to/kubeconfig # 集群内运行时可省略 workload_provider agent-sandbox [agent_sandbox] shutdown_policy Delete各参数含义结合 config.py 与 示例配置 可确认取值范围与默认值配置项说明runtime.type运行时类型此处必须为kubernetes注意docker运行时不允许出现[agent_sandbox]块配置校验会直接报错见 config.py 的约束agent_sandbox block must be omitted when runtime.type dockerruntime.execd_imageexecd init 容器镜像server 会将其注入每个沙箱 Pod 的 init container用于在沙箱内提供命令执行/文件操作 APIkubernetes.namespace沙箱工作负载所在命名空间kubernetes.kubeconfig_pathkubeconfig 路径集群内运行时留空即可使用 in-cluster 配置kubernetes.workload_provider取值batchsandbox或agent-sandbox大小写不敏感由 provider 工厂注册表解析不指定时默认取第一个注册的 provider通常为batchsandbox见 provider_factory.pyagent_sandbox.shutdown_policy沙箱过期后的处置策略仅接受Delete或Retain默认Deleteagent_sandbox.template_file可选agent-sandbox Sandbox CR YAML 模板文件路径用于覆盖 pod 模板未配置则不合并模板agent_sandbox.ingress_enabled可选是否预期启用 ingress 路由默认true另外配置校验中存在一个联动规则当kubernetes.workload_provider agent-sandbox且未写[agent_sandbox]块时server 会自动填充一个默认值的AgentSandboxRuntimeConfig默认shutdown_policy Delete反之写了[agent_sandbox]块但 provider 不是agent-sandbox也会报错见 config.py。3. 启动 serveropensandbox-server源码纵深AgentSandboxProvider 如何落地一个 Sandbox CR理解示例背后发生了什么关键在 agent_sandbox_provider.py。CRD 坐标与资源命名AgentSandboxProvider在构造时固定了 CRD 坐标agent_sandbox_provider.pyself.group agents.x-k8s.io self.version v1beta1 self.plural sandboxes这与“仅支持 v1beta1”的兼容性声明一一对应。sandbox ID 会被规范化为 DNS1035 label非法字符替换为-、去重连字符、超长时截断并追加 8 位 SHA-256 哈希后缀保证资源名在 K8s 中合法且可回查_to_dns1035_label。创建流程先构造 spec再合并模板create_workload的核心逻辑agent_sandbox_provider.py构造 spec 骨架其中就包含了文档所述的 server 强制字段spec { operatingMode: Running, service: True, shutdownPolicy: self.shutdown_policy, podTemplate: { metadata: {labels: labels}, spec: pod_spec, }, }Pod spec 组装_build_pod_spec会构造 execd init container来自runtime.execd_image、主容器用户镜像 注入OPENSANDBOX_ID环境变量、opensandbox-binemptyDir 卷并在请求了出网策略时通过apply_egress_to_spec追加 egress sidecar_build_pod_spec。模板合并template_manager.merge_with_runtime_values将 spec 与用户模板合并——文档中“包括合并自定义模板时 server 仍设置operatingMode/service”的行为正源于此模板管理器见 agent_sandbox_template.py。shutdownTime 语义请求不带过期时间时即使模板里写了shutdownTime也会被pop掉带过期时间时写入 ISO 8601 绝对时间戳。续期通过update_expirationpatchspec.shutdownTime实现agent_sandbox_provider.py。镜像拉取认证若请求携带镜像认证会额外创建以 Sandbox CR 为 owner 的 imagePullSecret失败时回滚已创建的 Sandbox CRagent_sandbox_provider.py。状态映射与端点解析状态推导get_status读取status.conditions中type Ready的条件——statusTrue映射为Runningreason为SandboxExpired/PodSucceeded映射为TerminatedPodFailed或平台约束不可调度映射为Failed无 Ready 条件时先回退到用status.selector查 Pod 的 IP/phase 做细粒度判定Allocated/Pending否则为Pendingget_status。端点解析ingress 模式优先返回 ingress endpoint否则依次尝试status.selector选中的 Running Pod 的podIP、status.serviceFQDNget_endpoint_info。内部直连端点则直接取status.podIPsget_internal_endpoint。ingress 侧对偶实现OpenSandbox ingress 组件同样实现了 agent-sandbox providerwatchagents.x-k8s.io的资源以维护路由见 components/ingress/pkg/sandbox/agent_sandbox_provider.go这正是文档要求 server 与 ingress “一起升级”的原因。运行示例安装 Python SDKuv pip install opensandbox执行脚本uv run python examples/agent-sandbox/main.py脚本逐行解读main.py 展示了 OpenSandbox Python SDK 的最小用法domain os.getenv(SANDBOX_DOMAIN, localhost:8080) # OpenSandbox Server 地址 api_key os.getenv(SANDBOX_API_KEY) # server 启用 API key 鉴权时必传 image os.getenv(SANDBOX_IMAGE, ubuntu:22.04) # 沙箱镜像默认 ubuntu:22.04 config ConnectionConfig( domaindomain, api_keyapi_key, request_timeouttimedelta(seconds60), ) sandbox await Sandbox.create( image, connection_configconfig, timeouttimedelta(minutes10), # 沙箱 10 分钟过期映射到 CR 的 shutdownTime ) async with sandbox: execution await sandbox.commands.run(echo hello world) stdout execution.logs.stdout[0].text if execution.logs.stdout else print(fcommand output: {stdout}) await sandbox.kill()要点Sandbox.create的timeout参数对应上文的过期时间语义——server 会将其转成 Sandbox CR 的shutdownTime绝对时间戳若传None则 CR 中省略该字段commands.run执行命令并返回结构化执行结果脚本从execution.logs.stdout取首行文本sandbox.kill()主动销毁沙箱AgentSandboxProvider.delete_workload会以grace_period_seconds0删除对应的 Sandbox CRagent_sandbox_provider.py再由 agent-sandbox controller 级联清理 Pod。预期输出command output: hello world若在集群中观察应能在kubernetes.namespace指定的命名空间下看到一个agents.x-k8s.io/v1beta1的Sandbox资源名称为规范化后的sandbox-hash形式 label-safe 名其spec.operatingMode为Running、spec.service为true就绪后status.conditions中ReadyTruestatus.serviceFQDN填充后 ingress 即可路由。延伸阅读完整配置参考server/configuration.mdKubernetes 示例配置example.config.k8s.toml服务端 provider 实现agent_sandbox_provider.py、provider_factory.pyingress 侧 agent-sandbox 路由agent_sandbox_provider.go示例源码examples/agent-sandbox/main.py【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考