CLRK：基于 gVisor 和 MitM 防护的开源 AI Agent 运行时

CLRK

CLRK（我们将其发音为"clerk"）是一个面向LLM代理的Kubernetes原生运行时。它运行每个代理 在gVisor沙箱中，并透明地拦截所有出站流量——LLM API、MCP、工具调用——而无需 修改代理代码。该拦截点提供可观测性、策略执行和 基于路由的成本控制，让你能够洞察那些原本无法看到的代理内部情况。

工作原理

CLRK在gVisor沙箱中运行不受信任、框架无关的代理工作负载。 你以声明式方式描述一个代理——一个容器镜像 + 一个触发器 + 一个出站策略——然后CLRK 将其调度到沙箱工作节点池中。它自带调度器，因此代理启动不受 Pod创建延迟的影响。沙箱的每一字节输入输出都经过CLRK控制的透明 代理，因此平台能够看到并管理所有LLM API调用、MCP流量和出站 工具调用，而代理代码对此毫无感知。是的，这包括TLS加密的连接。

内部的代理可以是任何发起HTTP(S)调用的东西——一个使用OpenAI或 Anthropic SDK的Python脚本、一个Node MCP客户端、一个shell单行命令。无需特定的代理库；CLRK 在网络和进程边界进行拦截。参见 _examples/ 获取可运行的代理示例 (openai-bot, gemini-bot, cron-bot, jq-bot, MITM变体等)。

动机

在生产环境中运行代理会引发一系列问题，而通用容器 编排本身无法解决。CLRK旨在直接应对这些问题：

• 可观测性。 沙箱的所有输入输出I/O都会被拦截并记录，因此 LLM、MCP和远程工具调用的遥测数据是自动埋点的，而不是按框架逐一附加的。
• 治理。 防止沙箱逃逸，并在出站边界应用组织级策略 （代理可以连接到何处、可以使用哪些凭据）。
• 归因。 将代理循环关联到启动它的客户请求或触发器， 作为一等公民Invocation记录进行捕获。
• 零信任访问。 授予代理对内部服务的审计、授权访问， 而非全有或全无的网络访问。
• 可伸缩性。 同一模型既适用于无服务器突发场景，也适用于长期运行的"本地部署" Kubernetes集群。
• 可靠性。 简单、健壮的重试、负载丢弃，全部在Kubernetes 控制平面之外实现。

一个遵循治理原则的刻意设计选择：凭据从不驻留在代理内部。 面向AI提供商、MCP服务器和内部服务的API密钥 在请求时由出站MITM注入，从不通过Pod环境变量、挂载或参数传递——因此 被攻破的沙箱无法将其窃取。

架构

CLRK附带两个长期运行的二进制文件和一个CLI：

• cmd/controller-manager - 控制平面。运行 下方CRD的controller-runtime协调器，并嵌入一个聚合API 服务器，服务于clrk.apoxy.dev组。作为Deployment部署在Kubernetes上，但 也可以独立运行。它还托管UI仪表板。
• cmd/worker - 通过gVisor/runsc管理沙箱生命周期， 通过我们自定义的sentrystack插件设置每个沙箱的网络拦截， 使流量路由经过拦截路径。仅限Linux（//go:build linux，CGO）。
• cmd/clrk - 运维/开发CLI：install、upgrade、dev、 apply、get、logs、traces、status、run-task、context management，以及 local-cluster dev loop。

出口拦截。 出站流量被透明地捕获并通过 EgressGateway发送——这是一个基于Envoy的数据平面，具有TLS终止（MITM）和 自定义过滤器。在这里记录遥测数据、注入凭证 以及应用路由/治理策略（EgressL4Route、MCPRoute、AIProviderRoute、 出口/凭证/回退路由/日志/限流策略）。

遥测存储与导出。 被拦截的I/O变为Invocation记录， 由ClickHouse支持（通过ch-go驱动），并且可以通过/logs和 /traces子资源消费，也可以重新导出到OpenTelemetry接收器。

TaskAgent 与 DaemonAgent TaskAgent 用于触发的、运行到完成的工作（HTTP请求或cron），在共享worker pod上多路复用。DaemonAgent 用于具有重启策略的长期运行的agent进程。

API

CRD	用途
TaskAgent	短期agent执行（请求→沙箱→响应）
DaemonAgent	具有重启策略的长期agent进程
WorkerPool	worker pod集群（Deployment + Service）
EgressGateway	具有TLS终止模式的透明出口代理
EgressL4Route	L4出口路由规则
MCPRoute	MCP协议路由
AIProviderRoute	特定AI提供商的出口路由
Invocation	被拦截的agent调用的属性记录（由ClickHouse支持）

仓库布局

路径	目录
api/clrk/v1alpha1/	CRD 类型（Apache-2.0）
client/	生成的 Kubernetes clientset、listers、informers（Apache-2.0）
internal/controller/	controller-runtime 协调器
internal/worker/, internal/sandbox/	沙箱生命周期（仅限 Linux）
internal/eg*, internal/extproc/, internal/egress/	Envoy 出口数据平面 + 拦截
internal/clickhouse/, internal/chwriter/, internal/otel*	遥测存储与导出
internal/install/, cmd/clrk/	安装程序与 CLI
codegen/	代码生成器配置（update.sh，header 样板文件）

常见问题

我的代理是否需要使用特定的框架或 SDK？

不。CLRK 在网络和进程边界进行拦截，因此任何进行 HTTP/S 调用的代理都可以工作。提供的示例使用了 OpenAI 和 Gemini SDK、纯 Shell 工具以及 MCP 客户端。

API 密钥存放在哪里？

不在代理中。凭证通过出口 MITM 在请求时通过 凭证注入策略注入——绝不会出现在 Pod 环境变量、挂载或参数中。被攻破的 沙箱没有机密可泄露。秘密材料本身安全地存放在 Kubernetes Secret 中。

沙箱是如何隔离的？

沙箱通过 gVisor（runsc）运行，以获得更强的系统调用 边界，每个沙箱位于自己的网络命名空间中，所有出口流量强制经过 拦截路径。

我可以在本地运行还是需要 Kubernetes 集群？

所有功能一应俱全！clrk dev 启动本地集群和开发循环。这也可用于在没有附近Kubernetes集群的情况下运行CLRK。clrk install / clrk upgrade 管理基于Kubernetes的部署。

为什么api/和client/的许可证与其他部分不同？

这样你就可以针对API进行构建并使用生成的客户端，而无需承担AGPL copyleft 义务。请参阅License。

CONTRIBUTING.md在哪里？

目前，不接受外部贡献。如果你遇到错误或有 功能请求，请在 GitHub仓库上提交一个问题。

这经过测试了吗？我找不到任何测试！

我们有测试，我们发誓！目前它们与我们的私有构建/测试 基础架构耦合，并且不公开可用。我们试图保持至少70%的单元 测试覆盖率，并对公共API进行集成测试。

这是用vibe编码的吗？

我们依赖AI辅助，但每一行输出在提交前都经过认真审查和测试。

许可证

CLRK根据GNU Affero General Public License v3.0 （AGPL-3.0）获得许可；请参见LICENSE。

Exception: api/和client/目录根据 Apache License 2.0获得许可；请参见api/LICENSE 和client/LICENSE。这些涵盖了公共API类型 （api/clrk/v1alpha1）以及生成的Kubernetes客户端/SDK，因此它们可以在没有AGPL copyleft义务的情况下被 导入和使用。