自托管 Claude Managed Agents 部署教程:从 Compose 到 Helm

Anthropic 11 月 12 日推出了自托管版 Claude Managed Agents,Agent 定义、会话和会话历史都可以留在自己的服务器上。发布包要找 Anthropic 客户团队申请,拿到以后怎么起?这篇按官方快速入门、Kubernetes 部署页和差异文档整理:先用 Docker Compose 在一台机器上跑通第一个会话,再看生产环境的 Helm 部署要准备什么,以及从托管版迁过来要改哪些地方。
先弄清楚它自托管的是哪一层
自托管的是 Managed Agents 这套服务本身:服务端、PostgreSQL 数据库,以及给每个会话单独开沙箱的 worker。Claude 模型不在本地跑,推理请求默认还是发给 Claude API,也可以在服务端设置里改成云厂商或自建的模型网关。事件本身的介绍见站内快讯 Claude Managed Agents 能自托管了。
| 部署方式 | 适合 | 组成 | 要注意 |
|---|---|---|---|
| Docker Compose | 开发、试用 | 服务端 + PostgreSQL + 10 个 worker | 明文 HTTP,默认只开本机 8400 端口 |
| Kubernetes(两个 Helm chart) | 生产,官方推荐 | cma-server + cma-sandboxes,数据库放集群外 | 需要 gVisor 节点和 NetworkPolicy |
前置条件
- 发布包(
.tar.gz),只能由 Anthropic 客户团队开通下载。 - 一个 Claude API 密钥,服务端调模型用。
- 最新版 Docker Engine 和 Compose 插件(命令是
docker compose,不是老的docker-compose)。 - 至少 2 个 CPU 的主机,x86-64 或 Arm 都行;CPU 更少时在
.env里把CMA_SANDBOX_CPUS设成实际核数。 - 本机装好
openssl和antCLI;首次构建要能访问 Docker Hub、Alpine 软件源和 GitHub Releases。
官方特别提醒:Agent 的工具在这台主机的容器里运行,Docker Engine 28.3.3 之前的某些版本还可能让局域网里的机器连到 8400 端口。所以开发栈要放在一台没有重要数据的机器上。
第一步:解压并写好 .env
tar -xzf <archive>.tar.gz && cd <archive>/compose
cat > .env <<EOF
CMA_PG_PASSWORD=$(openssl rand -hex 32)
ANTHROPIC_API_KEY=sk-ant-...
CMA_SERVER__API_KEY=$(openssl rand -hex 32)
CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
EOF
chmod 600 .env
用编辑器把 sk-ant-... 换成自己的 Claude API 密钥。另外三项是自动生成的:数据库密码、应用调用这台服务器用的服务端 API 密钥,以及加密已存凭据的密钥。umask 比 022 严的话,解压出来的二进制会丢掉执行权限,服务端容器起不来,先把 umask 设回 022 再解压。
如果是让 Claude Code 代跑这份快速入门,官方的要求是:.env 由人自己编辑,Agent 不索要密钥,也不打印 .env。
第二步:起栈并检查就绪
docker compose up --build -d
docker compose logs -f cma-server # 看到 msg="cma-server listening" 后 Ctrl+C
curl -s http://127.0.0.1:8400/cma-server/readyz
返回 "status":"ready" 就可以了。刚启动的几秒可能是 degraded;一直不变或返回 not_ready,就到返回里找状态为 failed 的检查项:upstream 说明 Claude API 拒绝了密钥,database 说明数据库登录或连接有问题。服务端始终起不来时,先看 docker compose logs migrate,这个一次性容器负责建表,必须以状态 0 退出。
第三步:建 Agent,跑第一个会话
另开一个终端专门跑 ant,让它指向自己的服务器。注意这里的 ANTHROPIC_API_KEY 填的是服务端 API 密钥:
export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)
把下面内容存成 quickstart-agent.md,再执行 ant apply --yes quickstart-agent.md。命令会先报一条找不到组织和工作区的 404 警告,在自己的服务器上属于正常现象。
---
name: Quickstart agent
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful assistant.
然后取出 Agent 和环境的 ID,开会话并连进去。Compose 栈的环境名叫 compose-sandbox:
AGENT_ID=$(ant beta:agents list --format raw \
--transform 'data.#(name=="Quickstart agent").id' --raw-output)
ENVIRONMENT_ID=$(ant beta:environments list --format raw \
--transform 'data.#(name=="compose-sandbox").id' --raw-output)
SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
--environment-id "$ENVIRONMENT_ID" --transform id --raw-output)
ant beta:sessions connect "$SESSION_ID"
在聊天界面里让它用 bash 工具执行 hostname。回复的主机名以 cma-sandbox- 开头,说明命令是在沙箱容器里跑的,没碰你的主机。回到第一个终端执行 docker ps --filter label=cma-server.sandbox,能看到这个容器;一轮对话结束大约一分钟后它会退出,下一条消息再起新容器。
两个终端分开用:带着 ANTHROPIC_BASE_URL 的那个终端里一旦执行 docker compose up,服务端就会调自己,而不是去调 Claude API。
常见坑
- 就绪检查一直 degraded、每轮都失败:多半是在设了
ANTHROPIC_BASE_URL的终端里起了栈。回到第一个终端重新docker compose up -d。官方给 Agent 的建议是在每条 compose 命令前加env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN。 - Agent 回复了,工具调用一直不结束:没有 worker 在轮询。用
docker compose logs sandbox查;连不上 Docker socket 的话,在.env里设CMA_DOCKER_SOCKET。 - worker 都在,调用还是卡住:10 个 worker 每个同时只服务一个会话,没发消息的会话也会占着 worker 最多一小时。把不用的会话
ant beta:sessions archive掉。 - 想试服务端自带的网页控制台:要单点登录,快速入门里用的是模拟登录提供方,谁能连上都能拿到管理员令牌,只能配一次性数据用。
上生产:Kubernetes 要先备齐这些
生产用发布包里的两个 Helm chart:cma-server 在 cma-server 命名空间里跑建表任务和两个服务端实例;cma-sandboxes 在 cma 命名空间里跑调度器,给每个会话单独开一个沙箱 Pod。官方示例用的是 GKE,其他集群步骤相同,集群前提和部分 chart 参数不同。开工前要有:
- Kubernetes 1.30 以上,装好 Agent Sandbox 控制器、能跑 gVisor 的节点,网络插件要能执行 NetworkPolicy。
- 集群能访问的 PostgreSQL 16 以上数据库,它不放进两个 chart 里。
- 一个集群能拉取的镜像仓库:服务端、调度器、沙箱三个镜像要用
docker buildx自己构建,标签等于发布版本号。 - 集群管理员权限(要建命名空间、Role 和 ClusterRoleBinding),以及
helm、kubectl、openssl、ant。
凭据加密密钥要自己留一份。卸载 chart 会连 Secret 一起删掉,数据库虽然还在,没有这把密钥就用不了。卸载时先停调度器、删沙箱,因为 helm uninstall 会删掉约束沙箱的网络策略,已经开出来的沙箱却还在跑。
从托管版迁过来,要改的地方
托管版上的东西不会复制过来,Agent、Skill、凭据和记忆库都得在自己的服务器上重建。差异文档里影响最大的几条:
| 托管版做法 | 自托管版 | 替代做法 |
|---|---|---|
Files API、file 资源 | 不支持 | 文件放进 worker 工作目录;图片、PDF 用 base64 发 |
| 预置 docx/pdf/pptx/xlsx Skill | 拒绝保存 | 从 skills 仓库下源码,当自定义 Skill 上传 |
| 定时部署、Webhook | 没有 | 自己的 cron 开会话;靠事件流跟进 |
mcp_oauth 凭据 | 拒绝创建 | 改存 static_bearer,过期前自己换令牌 |
| MCP 服务器、网页工具 | 默认全关 | 在 mcp.allowed_hostnames 里逐个列主机;web_tools.enabled: true |
还有两处容易漏:MCP 主机名精确匹配,不支持通配符和子域名,没列进白名单的,服务端会拒绝保存引用它的 Agent;网页工具开了以后,web_search 也只在推理提供方为 anthropic、vertex、foundry 时可用,其他提供方下 Agent 照样保存,模型却调不到它,也不报错。自托管版多出来的能力包括单点登录、接自己的密钥管理器,以及给 MCP 调用签短期身份令牌。如果之前用 EKS 给编码 Agent 建沙箱那套思路做过隔离,可以对照着看自托管版的网络策略怎么配。
完成标准
readyz返回ready,Agent 回报的主机名以cma-sandbox-开头。.env权限是 600,Claude API 密钥没出现在终端输出或 Agent 对话里。- 生产前的清单已对过:集群前提、PostgreSQL 16+、自建镜像、加密密钥的备份。
- 现有应用用到的功能,已按差异表标出「照常可用」「要改做法」「没有替代」。
最后
拿到发布包后,先在一台空机器上把 Compose 栈跑到 hostname 返回 cma-sandbox- 这一步,再按差异表盘点自己的 Agent 要改什么,然后再碰 Helm。