Plimsoll：为 AI Agent 生成的代码提供自托管沙箱

plimsoll 在沙箱内运行不受信任的代码，比如 AI 智能体编写的代码，并且每个结果都会说明该沙箱的强度。请求可以要求最低强度；如果沙箱更弱，则什么都不会运行。

这个名字来自Plimsoll 线，即画在船体外侧、任何人都能查看的载重限制线。plimsoll 对隔离层级也做同样的事：一次运行周围那道墙有多强，用四个级别之一来表示，从最弱开始：process，container，kernel，vm。该层级是每个结果上的一个值，而不是数据手册里的一句话。请求可以设置一个下限，即它会接受的最弱层级，官方 Go 客户端会在结果返回时再次检查该层级。

同一套机制让 plimsoll 不仅能隔离智能体编写的代码，还能对它进行考试。内置于模拟镜像中的试验运行器会让智能体的程序针对该程序无法读取的场景运行：每个场景都通过一个在程序启动前就被删除的文件送达运行器。每次运行都会返回所发送请求和所返回结果的 SHA-256 哈希，官方客户端会重新计算（如何）。守护进程之外的一个独立程序，plimsoll-attest，会对已检查的结果签名，拒绝缺少一环的调用链，并重放一次运行。考试本身（模拟系统、场景、及格分数）仍归你所有：plimsoll 提供边界和证据。

查看一次真实运行

一个 AI 智能体编写了一个控制器：一个在每个tick（这里指模拟的一个 10 ms 步长）读取系统状态并决定如何推动它的程序。plimsoll 让它针对一个模拟的倒立摆小车运行，即一辆在轨道上的小车，顶部铰接一根杆，控制器通过左右推动小车使杆保持直立。模拟器被编译为WebAssembly，一种在宿主程序内运行的可移植字节码，并内置到沙箱镜像中。控制器是调用方通过普通项目 API 发送的唯一文件，它运行在container层级。

倒立摆小车是控制工程中的标准教学问题。运行器是内置于镜像中的一个程序，它让控制器针对模拟器运行，记录该次运行的轨迹，即每个 tick 的每个状态，并将其哈希成一个指纹: 一个 SHA-256 哈希，因此相同的指纹意味着相同的数字。运行两次被接受的控制器，两个指纹就匹配。智能体的初稿有两个增益（其公式中的乘数）符号错误：它在 5.96 秒处丢掉极点，其指纹也不同。

打开实时运行报告 ↗在浏览器中重放两次运行，阅读智能体编写的控制器，并查看该页面刻意不声称的内容。示例的一次执行会产生三次沙箱运行：被接受的控制器两次，初稿一次。用以下命令复现它们make docker-images && go run ./examples/oracle。

它做的两件事

它报告墙。每个结果都说明该次运行实际获得的隔离层级。每个请求都可以设置一个下限，而守护进程无法满足其下限的请求会在任何代码运行之前被拒绝：ErrInsufficientIsolation意味着什么都没运行。

res, err := provider.Sandbox.RunJavaScript(ctx, sandbox.Request{
    Code:             "console.log(6 * 7)",
    MinimumIsolation: sandbox.IsolationVM, // ErrInsufficientIsolation 意味着什么都没运行
})
// res.Isolation 报告实际运行的边界。

每一个什么都没运行的拒绝都被标记为拒绝，并附有原因（request，permission，protocol，unsupported，isolation，environment，capacity）。sandbox.NotDispatchedReason(err)读取该标记，无论provider（运行代码的后端）是在你自己的进程中还是在守护进程之后。没有该标记的错误可能是在代码启动之后出现的，因此自动重试永远不安全。标记只在一个把客户端请求 ID 带回来的应答上才算数，因此一个把某个请求的应答提供给另一个请求的代理，无法让一个实际运行过的调用读作“什么都没运行”（返回什么，以及它意味着什么）。

该层级是守护进程收集的证据：它的配置及其自身的启动检查。它不是证明，即来自硬件的、关于正在运行什么软件的密码学证明，而这里的任何 provider 都不提供这种证明。docs/isolation-tiers.md列出了每个层级所依赖的内容。

它让智能体编写的代码可以调用你的 API，而无需持有你的凭证、你的 API 地址或开放的网络访问。一个授权授予一次运行调用某个 API 所列路由的权限。代码通过 plimsoll 放入沙箱的一个小型客户端进行调用，而broker，即 plimsoll 位于沙箱之外、发起真实调用的部分，会检查调用方和确切的路由，然后自行附加凭证。该凭证是mintedper run：plimsoll 每次运行只请求一次，因此它可以是一个全新的短期令牌，而且它永远不会进入沙箱。绕过客户端、手动发起调用的代码无法更进一步，因为执行规则的是 broker，而不是客户端。参见docs/capability-grants.md。

在智能体框架中使用它

这些智能体框架可以通过它们自己的工具或代码执行器，将其模型的代码交给 plimsoll（Trigger.dev，其中之一，是一个托管的 TypeScript 任务运行器）。每一行列出需要安装的内容、指南，以及一个页面，该页面回放从该框架的工具到沙箱再返回的已记录调用，包括被拒绝的调用。

给 Trigger.dev 智能体一个代码工具

这个TypeScript 附加组件为 Trigger.dev 上的聊天智能体提供一个executeCode工具。在带有会话的守护进程上，一个沙箱会为多次调用保留，每次调用是一个单元，代码在该对话所保留的运行记录的解释器内运行：变量和文件可以存活到下一次调用。每个工具结果都会说明它们能否存活、本次调用是否全新开始、它运行在哪个隔离层级，以及

的 SHA-256，这是一份关于发送和返回内容的凭据，客户端在返回前已对其进行检查。调用方会设置最低层级，因此较弱的提供方会在运行代码前拒绝。参见功能与部署指南以了解确切的保证和生产底线。这个可部署的 Trigger.dev 起始项目

一分钟内运行点什么

这个示例不需要守护进程、不需要 docker、不需要凭据，也不需要网络：它使用的是wasmprovider，它在QuickJS上运行 JavaScript，这是一个编译为 WebAssembly 的小型 JavaScript 引擎，运行在你自己的进程内。克隆和拉取 Go 模块确实会用到网络。

git clone https://github.com/plimsollmark/plimsoll && cd plimsoll
go run ./examples/minimal

provider   wasm
isolation  process
exit code  0
timed out  false
truncated  stdout=false stderr=false
duration   304ms
stdout     {"Engineering":59000000,"Sales":20300000,"Operations":9800000}

这个isolation行来自运行的结果，而不是示例自身的文本。process意味着完全没有操作系统层面的隔离墙：不要用它来运行恶意代码。同一段代码会在kernel层级运行，一旦gVisor安装完成。gVisor 是容器与你的机器内核之间的一层，它处理容器对操作系统本身的请求，因此代码永远不会直接与你的内核通信。sudo ./docker/install-gvisor.sh会安装一个固定版本的gVisor 发行版（一个确切的版本，只能通过编辑此仓库来更改），并向 docker 注册其运行时runsc。程序的其他部分没有任何变化：

make docker-images   #构建项目镜像（plimsoll/sandbox），docker provider 会检查它是否存在
SANDBOX_PROVIDER=docker SANDBOX_DOCKER_RUNTIME=runsc go run ./examples/minimal

当SANDBOX_PROVIDER未设置时，plimsoll 使用 Disabled provider，它什么都不运行，因此代码执行绝不会被意外开启。

接下来： docs/getting-started.md会在同一台机器上走一遍相同的部分：启动守护进程、创建调用方凭据、编写你自己的客户端、观察某个层级拒绝一次运行，然后把守护进程从process迁移到kernel，而无需更改客户端。它还涵盖了嵌入 Go 包而不是运行守护进程的方式。

各部分所处的位置

flowchart LR
  A["Agent or MCP gateway (MCP: how an AI app offers tools to a model)"] -->|"Run: one payload, a protocol number, minimum_isolation"| AU

  subgraph D["plimsolld"]
    AU["authenticate the caller"] --> FL["compare the floor with current provider evidence"]
    FL --> DI["dispatch"]
    BR["broker: holds the minted credential, matches the exact route, counts every call"]
  end

  DI --> W["wasm: QuickJS on wazero (process tier)"]
  DI --> K["docker with runsc (kernel tier)"]
  DI --> V["e2b Firecracker (VM tier)"]

  W -. "host.get / host.post" .-> BR
  K -. "per-run Unix socket" .-> BR
  V -. "authenticated guard" .-> BR
  BR ==> |"your credential, attached host-side"| API["Your API"]

沙箱内部的代码，即guest，从不持有凭据，也从不直接访问网络。没有授权的运行完全没有网络。

隔离层级

plimsolld是 plimsoll 服务器。每个服务器只运行一个 provider，由SANDBOX_PROVIDER选择：

每一层级都依赖于守护进程的配置、提供方所报告的内容，以及启动时的一次真实测试运行；没有一项是证明。docs/isolation-tiers.md列出了每一层的证据，并展示请求如何设定其下限。会话用速度和保留的状态换取每次调用全新的沙箱：较早调用运行过的代码可以改变后续调用看到的内容，而一次具有 API 访问权限的调用需要一项允许会话的授权（docs/sessions.md）。一个会话就是一个信任域，plimsoll 将其绑定到经过身份验证的调用方，而不是该调用方的客户：一个通过单一凭证运行众多客户代码的服务必须把每个客户放在各自的会话中（谁可以共享一个会话）。docker provider 还可以应用随附的seccomp配置文件，这是一份其容器可以发起的唯一系统调用（对内核的请求，例如打开文件）的列表（docs/seccomp.md）。

这与其他用于智能体代码的自托管沙箱（E2B 的自托管版本、microsandbox、NVIDIA OpenShell、Kubernetes agent-sandbox 以及另外八个）相比如何，每一个都根据其自身文档描述，并附上 plimsoll 的弱点：对比（INTERNAL · plimsoll site →）。

更多真实运行

状态，直说

• 1.0 之前，单一作者，尚无外部用户。破坏性变更不带弃用路径，这是有意为之。
• 从未进行过第三方安全审计，作者自己的自审账本也未公开。SECURITY.md说明了存在什么、价值几何，以及你可以自己检查什么。
• CI 公开运行这道关卡，每项检查都说明它运行了什么。该审计工作流有三个作业。audit在每次推送到make audit时运行普通的main以及每个拉取请求：构建、vet、竞态测试、lint、buf lint、生成代码漂移检查，以及govulncheck。在audit之后，clients运行make clients-suite：npm ci在clients/typescript和examples/trigger-chat中，然后以必需模式运行audit-docker中的 Python 和 TypeScript Go 测试包。缺少运行时、依赖或被跳过的 Go 测试都会使该作业失败。audit也遵循make docker-suite并在镜像已准备好的情况下以必需模式运行audit-docker：缺少守护进程、缺少镜像或被跳过的测试都会使作业失败。因此一个绿色的noexec意味着 docker 套件在 runc 下使用随附的 seccomp 配置文件运行，并证明了只读根目录、大小合适的可写挂载，以及 broker 的拒绝。gvisor 工作流在 runsc（内核层级）下从固定版本的安装器运行同一套件。竞态检测器在普通审计作业和两个 docker 套件作业中运行；客户端作业不运行它。没有任何检查会演练 E2B 或 Docker Cloud Sandboxes：这些套件驱动的是实时付费服务，被刻意从不接入运行器。参见

CONTRIBUTING.md

。了解它如何工作如果你更愿意阅读而不是克隆，交互式课程是最快的入门方式。先从Plain English了解 API 之前的概念，或者用Quick start运行一些东西。这些文档使用的每个术语在术语表中都有一句话定义。课程位于.htmldocs/trainers/

并可离线使用：在浏览器中打开克隆中的任意文件即可。GitHub 会将

文件显示为源码而不是渲染它们，这就是为什么上面的链接指向已发布的副本。

许可证

Apache-2.0.