每个会话运行一个沙箱
通过 Kubernetes 上的 Helm chart、启动脚本或 SDK 轮询器,为每个会话提供其专属的自托管沙箱。
在"sandbox-per-session"(每个会话一个沙箱)模式中,每个会话都在一个全新的沙箱中运行,该沙箱可以拥有自己的文件系统、资源限制和网络控制。要将其与其他模式进行比较,请参阅选择部署模式。
您可以通过三种方式进行设置:
- Kubernetes 上的 Helm chart: Anthropic 的调度器(dispatcher)认领工作,并在您的集群上为每个会话启动一个 pod。
- 启动脚本:
antCLI 认领工作并调用您的脚本,由脚本在任意平台上启动沙箱。 - SDK 轮询器: 由您自己的代码认领工作并启动沙箱。
在 Kubernetes 上运行沙箱之后的各节适用于启动脚本和 SDK 轮询器。
在 Kubernetes 上运行沙箱
Anthropic 发布了一个 Helm chart cma-sandboxes 及其镜像。该 chart 在您自己的 Kubernetes 集群上为每个会话运行一个沙箱。它的调度器轮询环境的工作队列,并为每个会话分配一个专属的 pod:
- 隔离: 每个 pod 都在 gVisor 下运行,并受 chart 的网络策略保护。它拥有自己的文件系统和资源限制。只有调度器持有环境密钥。
- 会话亲和性: 会话中的每条消息都会发送到该会话的沙箱。会话空闲 30 分钟后(chart 的
sandbox.idleTimeout设置的默认值),其 pod 会停止。其/workspace卷会一直保留,直到会话结束。下一条消息会在同一个卷上启动一个 pod。 - 预热池: 除 Google Kubernetes Engine (GKE) 外,chart 会保留两个就绪的 pod 供新会话使用(chart 的
sandbox.warmPoolSize设置的默认值)。
沙箱 pod 运行 ant CLI worker。它们支持使用默认同步设置的记忆存储,但不支持自定义工具。
安装 chart
该 chart 可在 GKE、Amazon EKS 及其他集群上运行。安装之前,请先完成以下设置:
- 在集群中: Agent Sandbox 控制器(在 GKE 上为 Agent Sandbox 插件)、运行 gVisor 的节点,以及强制执行 NetworkPolicy 的网络插件。
- 在您自己的命名空间中: Restricted Pod Security Standard 标签、包含环境 ID 和环境密钥的 Secret,以及调度器的 TLS 证书。
GitHub 上的安装指南提供了每种集群的设置步骤,还涵盖了升级和密钥轮换。
将您的设置保存为 cma-values.yaml。如果此文件中缺少这三项设置,安装将失败:
platform: gke # or eks, or generic for any other cluster
egress:
# The chart already blocks the private ranges. List your other addresses
# that sandboxes must not reach.
clusterCIDRs:
- 203.0.113.10/32 # your cluster's Kubernetes API endpoint
cmaServer:
public: true # the Claude API has a public address安装指南列出了取决于您集群的设置,例如 GKE Autopilot 上的 gke.dns。它还说明了何时用 egress.clusterIsPrivate: true 代替 egress.clusterCIDRs。
然后,安装 chart:
helm install cma \
oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
--version 0.1.0 \
--namespace cma \
-f cma-values.yaml \
--wait安装完成后,运行安装指南中描述的预检检查。
向沙箱镜像添加工具
发布的沙箱镜像是包含 bash、curl、jq 和 ant CLI 的 Alpine Linux。chart 以只读根文件系统和非 root 用户身份运行它,因此智能体无法在会话期间安装软件包。
要为您的智能体提供更多工具(例如 Python 或 Git),请基于该版本标签从仓库构建这两个镜像。安装指南的 Install 部分提供了相关命令。将镜像以 cma-dispatcher 和 cma-sandbox 为名推送到您的镜像仓库,并使用 chart 的版本作为标签。然后,将 image.registry 设置为该镜像仓库。如果您固定了镜像摘要,请使用您自己镜像的摘要。
限制网络出站流量
默认情况下,chart 的网络策略允许沙箱访问公共 IPv4 互联网。它们会阻止私有地址范围、云元数据服务器以及 egress.clusterCIDRs 中的地址。遭受"prompt injection"(提示注入)的智能体可以将其读取的内容发送到其沙箱能够访问的任何地址。安装指南中的 Network egress 提供了详细信息。
- 启用 Dataplane V2 的 GKE: 设置
egress.mode: fqdnGke,将连接限制为egress.fqdnGke.hosts中主机的 443 端口。请在该列表中保留api.anthropic.com,并添加您的智能体命令所需的每个主机。与默认模式不同,此模式没有阻止范围列表。它允许所列主机名称解析到的任何地址,因此只列出您信任其 DNS 的主机。沙箱仍然可以通过 DNS 查询向外发送数据。 - 其他集群和未启用 Dataplane V2 的 GKE: 默认模式是唯一的模式。
- 所有集群: 网络策略不涵盖集群自身节点监听的端口。请参阅安装指南中的 Node isolation you own。
使用启动脚本启动沙箱
主机上的轮询器认领工作,并为每个工作项调用一次您的脚本。该脚本为这一个会话启动一个沙箱。
构建沙箱镜像
安装
ant并将ant beta:worker run设置为入口点。沙箱启动时,它会从环境变量中读取会话详细信息,处理该会话,然后退出。基础镜像必须提供/bin/bash;构建过程仅使用curl下载ant。DockerfileFROM your-base-image ARG ANT_VERSION=2.11.0 ARG TARGETARCH RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \ curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \ | tar -xz -C /usr/local/bin ant WORKDIR /workspace VOLUME /workspace ENTRYPOINT ["ant", "beta:worker", "run"]编写启动脚本
该脚本将会话详细信息转发到一个全新的沙箱中。它要求轮询器主机上安装
jq。spawn.sh#!/bin/bash # spawn.sh:每个已认领的工作项调用一次 # 已认领的工作项以 JSON 形式通过 stdin 传入。 ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')" export ANTHROPIC_WORK_SECRET mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID" exec docker run --rm \ -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \ -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \ -e ANTHROPIC_WORK_SECRET \ -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \ your-image轮询器会设置
ANTHROPIC_WORK_ID、ANTHROPIC_ENVIRONMENT_ID、ANTHROPIC_SESSION_ID和ANTHROPIC_ENVIRONMENT_KEY。只有当您在轮询器主机上设置了ANTHROPIC_BASE_URL时,它才会传递给脚本。脚本从标准输入上工作项的 JSON 中读取ANTHROPIC_WORK_SECRET。请参阅环境变量。/host/outputs是您选择的主机目录。将其挂载到/workspace后,您可以在沙箱退出后取回会话的交付成果。该挂载还会包含下载的skills/目录树以及所有中间文件。启动轮询器
ant beta:worker poll --on-work ./spawn.sh
转发工作项的机密
每个被认领的工作项都可以携带一个 Anthropic 为该会话签发的 secret。运行该会话的 worker 需要它来挂载记忆存储。
在同一进程中认领并运行会话的 worker 会自行传递该机密。使用 run() 的 EnvironmentWorker 就是这样的 worker,不带 --on-work 的 ant beta:worker poll 也是。当您自己的代码位于认领和 worker 之间时,需要由您转发该机密:
| 您认领工作的方式 | 机密的到达形式 | 传递给 worker 的方式 |
|---|---|---|
ant beta:worker poll --on-work | 脚本标准输入上工作项 JSON 的 secret 字段 | 沙箱环境中的 ANTHROPIC_WORK_SECRET |
Python、TypeScript 或 Go SDK 的 work.poller() | 每个被认领工作项的 secret 字段 | 沙箱环境中的 ANTHROPIC_WORK_SECRET,或 handle_item() 的 work_secret 参数 |
只将机密传入为该会话服务的沙箱,并且切勿记录它。有关它与环境密钥的关系,请参阅安全模型。
从 SDK 轮询器启动沙箱
要从您自己的代码而不是 ant beta:worker poll --on-work 认领工作,请使用 Python、TypeScript 或 Go SDK 中的轮询器:work.poller()。它轮询队列并将每个被认领的会话交给您,由您启动沙箱:
import asyncio
import os
from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork
SANDBOX_ENV = (
"ANTHROPIC_ENVIRONMENT_ID",
"ANTHROPIC_ENVIRONMENT_KEY",
"ANTHROPIC_WORK_ID",
"ANTHROPIC_SESSION_ID",
"ANTHROPIC_WORK_SECRET",
"ANTHROPIC_BASE_URL", # forwarded only when set on this host
)
async def launch_container(work: BetaSelfHostedWork) -> None:
print(f"claimed session {work.data.id}")
# 将 `docker run` 替换为您自己的沙箱启动器。转发环境
# 密钥(切勿转发您的 API 密钥)以及工作项的每会话机密:沙箱内的 worker
# 需要该机密来挂载会话的记忆存储。
env = os.environ | {
"ANTHROPIC_WORK_ID": work.id,
"ANTHROPIC_SESSION_ID": work.data.id,
"ANTHROPIC_WORK_SECRET": work.secret or "",
}
forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
launcher = await asyncio.create_subprocess_exec(
"docker", "run", "--rm", "--detach", *forward, "your-image", env=env
)
await launcher.wait()
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
async for work in client.beta.environments.work.poller(
environment_id=environment_id,
environment_key=environment_key,
auto_stop=False, # the launched sandbox owns the stop call
):
await launch_container(work)
asyncio.run(main())在沙箱内运行 SDK worker
当沙箱必须提供自定义工具或使用非默认的记忆同步设置时,请将 ant beta:worker run 入口点替换为 SDK 入口点。该入口点构造 EnvironmentWorker 并调用 handle_item(),后者读取启动脚本所转发的相同 ANTHROPIC_* 变量。
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
async def main() -> None:
async with AsyncAnthropic(
auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
) as client:
worker = EnvironmentWorker(client, workdir="/workspace")
# 不带参数时,handle_item() 会读取启动脚本转发的
# ANTHROPIC_* 变量,包括 ANTHROPIC_WORK_SECRET。
task = asyncio.create_task(worker.handle_item())
# 在容器停止时取消任务,可让 worker 在退出前上传
# 已更改的记忆文件并删除存储目录。
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())为会话准备文件
Anthropic 不会将文件或 GitHub 仓库挂载到自托管沙箱中。要提供会话特定的文件:
- 在会话的
metadata字段中传递文件引用,例如 S3 路径或提交 SHA。 - 在您的启动脚本或
--on-work处理程序中,获取会话(GET /v1/sessions/{session_id})并读取metadata。被认领的工作项携带会话 ID,但不携带元数据。 - 在任何工具运行之前,将文件准备到工作目录中。
cURL 示例从 ANTHROPIC_AUTH_TOKEN 读取访问令牌。要获取访问令牌,请按照设置联合中的说明,使用默认的 workspace:developer 范围设置 Workload Identity Federation。然后,按照从您的工作负载进行身份验证中所示,将您工作负载的身份令牌交换为访问令牌。仅在运行 cURL 示例的 shell 中设置 ANTHROPIC_AUTH_TOKEN,因为它的优先级高于您的联合设置。身份验证列出了 API 接受的其他凭据,例如快速入门中的 API 密钥。
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
metadata={"input_file": "s3://my-bucket/data.csv"},
)后续步骤
读取队列深度,干净地停止会话和 worker,并修复常见故障。
此页面对您有帮助吗?