LiteLLM Agent Platform深度解析：K8s沙箱+凭证保险箱托管Claude Code，460星MIT开源

发布时间：2026-05-22 12:10 | 原文链接

LiteLLM Agent Platform（LAP）是 BerriAI 团队推出的自托管 AI 编码代理运行平台，解决了一个核心安全问题：当 Claude Code、Codex 等编码代理需要调用外部 API 时，如何确保它们永远拿不到真实的 API 密钥？LAP 通过 Kubernetes 沙箱 + Vault Sidecar 凭证代理的架构，让代理进程只能看到占位凭据，真实密钥仅在网络边界做线级替换。本文从架构设计、凭证隔离机制、安装部署、CLI 工具到源码结构做全面拆解，适合关注 Agent 基础设施安全的技术团队和架构师阅读。

目录
  1. 概述
     1.1 项目背景
     1.2 核心能力
  2. 核心架构
     2.1 五大组件
     2.2 请求生命周期
  3. Vault Proxy 凭证隔离机制
     3.1 存根凭据格式
     3.2 线级替换流程
     3.3 保留密钥与安全边界
  4. Sandbox 沙箱体系
     4.1 会话生命周期
     4.2 Harness 类型与接口
  5. 部署与安装
     5.1 无 K8s 本地开发模式
     5.2 本地 kind 集群模式
     5.3 生产环境部署
  6. CLI 与 API
     6.1 lap 命令行工具
     6.2 REST API
  7. 源码结构
  8. 技术亮点与局限
  9. 总结
    参考文献
1. 概述

1.1 项目背景

在日常开发中，使用 Claude Code、Codex 这类编码代理时，通常需要给它们真实的 API 密钥——这带来了安全隐患：代理进程可能将密钥写入日志、泄露到标准输出、或被第三方 MCP 工具截获。LiteLLM Agent Platform 的核心思路是：代理进程自始至终不持有真实密钥。

项目由 Y Combinator 支持的 BerriAI 团队开发，与明星项目 LiteLLM（40K+ Stars）同属一个组织。仓库采用 MIT 协议开源，当前 460 Stars、46 Forks、837 次提交。技术栈以 TypeScript 为主（84.8%），辅以 Shell、Dockerfile、Python 等。

  • 仓库地址：https://github.com/BerriAI/litellm-agent-platform
  • 文档站点：https://docs.litellm-agent-platform.ai
  • License：MIT

1.2 核心能力

  • Kubernetes 原生沙箱隔离：每个代理会话跑在独立 Pod 中
  • Vault Sidecar 凭证代理：代理进程只拿到 stub 占位凭据，真实密钥在出站 HTTPS 流量中由 sidecar 做线级替换
  • 多代理支持：Claude Code、Codex、opencode、Claude Agent SDK
  • 双协议接入：PTY over WebSocket（交互式终端）+ JSON Message API（自动化）
  • 三种部署模式：无 K8s 本地开发、kind 本地集群、AWS EKS 生产环境
  • 24 小时会话持久化：Ctrl-D 断开后会话保持存活，可随时重连
  • 自动空闲回收：24 小时无流量自动清理 Pod
2. 核心架构

2.1 五大组件

  • Web 服务（Next.js）：提供 UI 界面、REST API、会话编排。本地开发运行于 3000 端口
  • Worker 进程：后台运行的"会话生命周期协调器"，负责空闲 Pod 回收
  • PostgreSQL：存储代理配置、会话元数据、用户信息。迁移通过 Prisma ORM 管理
  • Kubernetes 集群：运行 kubernetes-sigs/agent-sandbox CRD，负责沙箱 Pod 的调度和生命周期
  • lap CLI：终端命令行工具，登录平台后一键启动沙箱代理

2.2 请求生命周期

一次完整的代理调用分为 3 个阶段：

流程执行说明：

  • 阶段一（会话创建）：客户端通过 Web UI、CLI 或 API 发起会话请求，Web 服务在 K8s 中创建对应的 Sandbox 自定义资源
  • 阶段二（Pod 初始化）：Sandbox Controller 接管 CR 并调度 Pod。Pod 启动时注入 Stub 凭据到 Harness 容器的环境变量中，然后克隆目标仓库、安装依赖
  • 阶段三（代理运行）：客户端通过 PTY WebSocket 或 JSON API 与代理交互。代理每次出站 HTTPS 调用都经过 Vault Sidecar，Sidecar 在请求离开 Pod 前完成凭据替换
  • 关键安全属性：真实密钥只存在于 Vault Sidecar 的进程内存中，不经日志、不经持久化存储、不经代理进程
3. Vault Proxy 凭证隔离机制

3.1 存根凭据格式

存根凭据遵循固定格式：stub_ 前缀 + 字母数字后缀。例如：

  • stub_github_a8f1 对应 GitHub Token
  • stub_litellm_bb20 对应 LiteLLM API Key

这些存根在 Pod 启动时注入到 Harness 容器的环境变量中。代理进程可以自由读取这些环境变量（如 echo $GITHUB_TOKEN），但永远只能看到存根值。

3.2 线级替换流程

替换发生在 HTTP 头部层面——Sidecar 检测到 Authorization: Bearer stub_litellm_bb20 后，替换为 Authorization: Bearer sk-real-key-xxxx。代理进程完全不知道替换发生过，目标 API 收到的也是正常的真实密钥。

3.3 保留密钥与安全边界

平台预留了 9 个环境变量名，用户不能通过 API 覆盖它们：

  • REPO_URL / BRANCH — 仓库地址和分支
  • LITELLM_API_KEY / LITELLM_API_BASE / LITELLM_DEFAULT_MODEL — LiteLLM 网关配置
  • AGENT_PROMPT / AGENT_REQUIREMENTS — 代理指令
  • PORT — 服务端口
  • GIT_TOKEN — 由 entrypoint 在 git clone 时使用后立即擦除

如果要让代理执行 git push 或 gh pr create 等操作，应使用 GITHUB_TOKEN 或 GH_TOKEN，它们会正常通过 Vault 代理持久存在。

安全保证的核心是：即使代理以 --bypass-permissions 模式运行（完全跳过权限检查），它也无法泄露真实密钥——因为代理进程从未持有过它们。真实密钥只存在于 Sidecar 的进程内存中，不落盘、不入日志、不进代理的内存空间。

4. Sandbox 沙箱体系

4.1 会话生命周期

每个沙箱是一个 K8s Pod，包含 Harness 容器和 Vault Sidecar 两个容器。会话有四种状态：

空闲超时机制：

  • 处于 ready 状态且 24 小时无任何流量的会话，由 Worker 的 Reconciler 自动回收
  • 每次消息或终端交互都会重置空闲倒计时
  • 在 lap 中按 Ctrl-D 仅断开终端连接，不终止会话——会话保持存活，可随时重连

4.2 Harness 类型与接口

平台提供四种代理接入方式，分为两大类：

两类接口的差异：

  • PTY 模式：Claude Code 和 Codex 是 TUI（终端界面）工具，通过 WebSocket 将远程 Pod 的 TTY 附加到本地终端。用户使用 lap CLI 工具接入，体验等同于本地运行
  • JSON API 模式：opencode 和 Claude Agent SDK 是编程式代理，通过 POST /sessions/{id}/message 发送结构化消息，适合集成到自动化流程中
5. 部署与安装

5.1 无 K8s 本地开发模式

适用于只需要 JSON API 代理（opencode、Claude Agent SDK）的场景，完全跳过 Kubernetes。

核心原理：设置 LOCAL_SANDBOX_URL=http://localhost:4096 让平台绕过 K8s，将会话请求直接路由到本机运行的 Harness 进程。设置 WARM_POOL_SIZE=0 阻止 Reconciler 尝试预配 Pod。

关键环境变量配置：

  • DATABASE_URL：直接（非连接池）Postgres 连接
  • MASTER_KEY：本地开发设为 sk-local-dev
  • LITELLM_API_BASE：LiteLLM 网关地址
  • LITELLM_API_KEY：网关密钥
  • ENCRYPTION_KEY：Base64 编码的 32 字节密钥，用 node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" 生成
  • LOCAL_SANDBOX_URL：设为 http://localhost:4096
  • WARM_POOL_SIZE：设为 0
  • IN_CLUSTER：设为 false

启动步骤：

  • 终端 1：npm install && npm run dev 启动 Web 服务（端口 3000）
  • 终端 2：进入 harnesses/claude-agent-sdk，配置环境变量后 node dist/server.js 启动 Harness（端口 4096）
  • 连接 CLI：lap login 指向 http://localhost:3000，然后 lap my-sdk-agent

会话从创建到 ready 状态通常在 2 秒内完成。

5.2 本地 kind 集群模式

需要 Docker Desktop、kind、kubectl、helm 和 LiteLLM 网关。

两步启动：

  • 步骤一（配置集群）：运行 bin/kind-up.sh。脚本是幂等的——创建一个名为 agent-sbx 的 kind 集群，安装 agent-sandbox controller，加载 Harness 镜像
  • 步骤二（启动服务）：docker compose up。启动 Postgres、执行 Prisma 迁移、启动 Web 服务（端口 3000）和 Worker

此后打开 http://localhost:3000，使用 MASTER_KEY 登录，创建代理即可。TTY 型代理（Claude Code、Codex）必须走此模式。

注意：DATABASE_URL 必须是直接 Postgres 连接（非 pgbouncer 连接池），因为 Prisma 迁移需要 advisory locks。

卸载：kind delete cluster --name agent-sbx

5.3 生产环境部署

推荐方案：AWS EKS 运行沙箱集群 + Render 托管 Web 和 Worker 服务。

  • bin/eks-up.sh：配置 EKS 集群和节点组，安装 Sandbox Controller
  • deploy/render/README.md：Render Blueprint，一键部署 Web + Worker

安全警告：绝对不要在生产环境设置 K8S_SKIP_TLS_VERIFY=true——这会完全禁用 TLS 验证。

6. CLI 与 API

6.1 lap 命令行工具

lap 是用户与平台交互的主要入口。

安装方式：

  • 1
  • 2
  • 3
git clone https://github.com/BerriAI/litellm-agent-platform.gitcd litellm-agent-platform/cli && npm installln -sf "$PWD/bin/lap.mjs" ~/.local/bin/lap

常用命令：

  • lap login：登录平台实例，提供 LAP URL 和 MASTER_KEY。凭据持久化到 ~/.lap/config.json
  • lap：无参数运行，弹出交互式代理列表，选择后启动沙箱 Pod 并附加本地终端到其 TTY
  • lap <agent-name>：直接连接到指定名称的代理
  • Ctrl-D：断开终端连接但不终止会话。会话保持 24 小时

6.2 REST API

平台提供完整的 REST API 用于自动化场景。

创建代理：

  • 1
  • 2
  • 3
  • 4
curl -X POST $LAP_URL/api/v1/managed_agents/agents \  -H "Authorization: Bearer $MASTER_KEY" \  -H "Content-Type: application/json" \  -d '{"name":"my-claude","harness_id":"claude-code","model":"anthropic/claude-sonnet-4"}'

创建会话并传入敏感凭据：

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl -s $LAP_URL/api/v1/managed_agents/agents/$AGENT_ID/session \  -H "Authorization: Bearer $MASTER_KEY" \  -H "Content-Type: application/json" \  -d '{    "title": "open a PR",    "env_vars": {      "GITHUB_TOKEN": "ghp_...",      "CIRCLECI_TOKEN": "cci_..."    }  }'

会话环境变量约束：

  • 最多 50 个键
  • 总大小不超过 16 KB
  • 键名必须匹配正则 ^[A-Za-z_][A-Za-z0-9_]*$
  • 不能覆盖保留键名

对于 API 型代理（opencode、Claude Agent SDK），通过 POST /sessions/{id}/message 发送消息。

7. 源码结构

仓库目录组织清晰，按功能分层：

技术栈全貌：

  • 应用框架：Next.js（Web 服务）、Express（部分后端路由）
  • 数据库：PostgreSQL + Prisma ORM
  • 容器编排：Kubernetes（kind 本地 / EKS 生产）
  • E2E 测试：Playwright
  • 代码检查：ESLint
8. 技术亮点与局限

技术亮点：

  • 凭证零泄露保证：即使代理以 bypass-permissions 模式运行，也无法泄露真实密钥——这是架构级的不可绕过安全属性，而非代码级的检查
  • 存根凭据的简洁设计：用 stub_ 前缀 + 字母数字后缀的固定格式，无需复杂的凭据映射协议，实现透明且可调试
  • 双接口范式：PTY over WebSocket 覆盖交互场景，JSON Message API 覆盖自动化场景，两种范式共享同一套 Vault + Sandbox 基础设施
  • 三模式部署覆盖全生命周期：无 K8s 的快速原型 → kind 本地集群的功能验证 → EKS 生产部署，平滑演进
  • 24 小时会话持久化 + 自动回收：在灵活性和资源效率之间取得平衡
  • 开源协议友好：MIT License，无使用限制

当前局限：

  • 正式版本未发布：仓库虽有 837 次提交但无任何 Release Tag 或 Semver 版本号，尚处于早期阶段
  • 强依赖 LiteLLM 网关：所有模型调用必须经过 LiteLLM Gateway，无法直连 Anthropic/OpenAI API——这对已使用其他网关的团队增加了架构耦合
  • K8s 运维门槛：生产环境需要自行管理 EKS 集群，对缺乏 K8s 经验的团队有较高学习成本
  • 社区规模小：460 Stars、11 Open Issues，相比母项目 LiteLLM（40K+ Stars）差距巨大，生态尚未形成
  • 仅支持 4 种代理：Harness 扩展机制未公开文档化，添加新代理类型需要直接修改源码
  • Apple Silicon 兼容性：文档提示存在特定问题，需参考 CONTRIBUTING.md
9. 总结

LiteLLM Agent Platform 的核心价值在于用架构手段而非代码检查来保证凭据安全——代理进程物理上无法接触真实密钥，因为替换发生在网络边界。这个设计思路对任何需要给 AI 代理授予外部 API 访问权限的场景都有借鉴意义。

关键结论：

  • 适合谁：需要在团队内部托管编码代理、对凭据安全有刚性需求的团队，尤其是已经使用 LiteLLM 网关的组织
  • 不适合谁：仅需单机使用 Claude Code 的开发者（直接用官方 CLI 更简单）；已有成熟 K8s 运维体系但不想引入 LiteLLM 网关依赖的团队
  • 当前成熟度判断：设计思路清晰、架构完整，但处于 pre-release 阶段——可以用于原型验证和技术研究，不建议直接上生产
  • 同类竞品对比：相比通用 Sandbox 方案（yolobox、sbox），LAP 提供了从 K8s 编排、凭据管理到 CLI 工具的完整闭环；相比企业级平台（Portkey），LAP 的 MIT 协议更友好但成熟度不足
  • 未来值得关注：BerriAI 的 YC 背景和 LiteLLM 的社区基础是强背书。如果项目在未来 6-12 个月发布正式版本并完善文档，有望成为自托管 Agent 基础设施的标准方案
参考文献

[1] LiteLLM Agent Platform GitHub 仓库：https://github.com/BerriAI/litellm-agent-platform

[2] LiteLLM Agent Platform 官方文档：https://docs.litellm-agent-platform.ai

[3] LiteLLM Agent Platform 架构文档：https://docs.litellm-agent-platform.ai/learn/architecture

[4] LiteLLM Agent Platform Sandbox 文档：https://docs.litellm-agent-platform.ai/learn/sandboxes

[5] LiteLLM Agent Platform Vault Proxy 文档：https://docs.litellm-agent-platform.ai/learn/vault-proxy

[6] LiteLLM Agent Platform 安装指南：https://docs.litellm-agent-platform.ai/installation

[7] LiteLLM Agent Platform Claude Code 快速开始：https://docs.litellm-agent-platform.ai/quickstart/claude-code

[8] kubernetes-sigs/agent-sandbox 项目：https://github.com/kubernetes-sigs/agent-sandbox

[9] LiteLLM AI Gateway：https://github.com/BerriAI/litellm

举报/反馈
分享到： 微博 QQ 空间
对本文内容有合作意向？
我们将在 1 个工作日内与您联系
留言咨询