SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 更新于 2026-10-18

如何自托管 Dormice 实现 AI 代理沙箱环境

Dormice 是兼容 E2B 协议的自托管代理沙箱方案。通过在 Linux VPS 上部署守护进程,您可以为 AI 代理提供安全隔离的执行环境。本文详细介绍其 SQLite 式的轻量架构、沙箱冻结机制以及如何通过修改 URL 前缀实现零代码迁移,助您降低高频调用沙箱的运行成本。

Dormice 是什么,以及它不是什么

Dormice 是一个自托管的代理沙箱:在您拥有的 Linux VPS 上运行一个 daemon,您的代理代码通过 HTTP 调用它,在隔离容器中运行不受信任的代码。程序按名称请求沙箱,无论沙箱之前处于什么状态,都会返回同一个沙箱;随后,程序在其中运行命令并读取输出。沙箱是一种编程资源,不是供您登录的机器。

这与向代理提供整台计算机的方式不同。供编码代理使用的一次性 VM 是一台可通过 SSH 登录的主机,允许代理随意修改,完成后再删除。Dormice 位于更低一层:它是程序在已有代码、需要安全运行环境时调用的执行 API。如果整台机器是工作单元,应使用一次性 VM。如果单个 exec 调用是工作单元,并且您每天需要运行 100 次而不是创建 100 台 VM,应使用 Dormice。

该项目称自身兼容 E2B。E2B 是托管沙箱服务,许多代理框架已经导入其客户端库。Dormice 使用自己的 URL 前缀提供相同协议,因此,指向您自己的服务器后,基于官方 e2b package 编写的应用仍可继续运行。应用代码无需修改。只需修改 2 个 URL 和 1 个 API key 前缀。

“agent 沙箱的 SQLite”在实际使用中意味着什么

SQLite 是嵌入应用的数据库,不是需要运维的服务。Dormice 直接借用了这个类比。每台机器运行一个 daemon,使用一个 SQLite 文件记录状态,监听一个 TCP 端口,并在旁边安装一个小型 gateway 提供 Web 控制台。不需要 Kubernetes,也不需要外部数据库服务器。daemon 会在其状态文件旁获取独占锁。因此,同一台机器上的第二个 daemon 会拒绝启动,而不会悄悄拆分状态。每个沙箱都位于创建它的机器上。README 现在将一个 fleet 描述为一个 gateway 加上其私有网络中的机器,但仍然说明:如果需要在机器之间迁移沙箱,或需要跨区域部署 fleet,应选择其他方案,并仔细评估。

这个概念的另一半与成本有关。托管沙箱按存在的每一秒计费,因此托管沙箱在设计上就是临时资源。Dormice 运行在已经付费使用的硬件上,因此其沙箱是永久的,静止时间越长,成本越低。沙箱会逐级进入低活动状态:active,然后是 frozen,再然后是 stopped,最后是 archived。每次 acquire 都会从沙箱当前所处的状态将其恢复。

冻结机制值得重点理解,因为它使永久保留每个 agent 的沙箱变得经济可行。以下是项目公布的实测数据,测试使用的是项目自己的硬件,不是您的硬件。

图表One idle sandbox before and after freezing, figures published by the project
此图表背后的数据
[
  {
    "label": "Active, holding 1 GiB",
    "resident_memory_mib": 1024,
    "wake_ms": 0
  },
  {
    "label": "Frozen",
    "resident_memory_mib": 5,
    "wake_ms": 50
  }
]

一个占用 1024 MiB 内存的空闲沙箱冻结后,常驻内存会降至 5 MiB,并可在约 50 ms 内恢复。进程会原地暂停并恢复,因此长期运行的 agent 在冻结期间仍能保留 shell 状态和未完成的工作。在据此规划容量前,请先在自己的主机上复现这一行为。

安装前主机需要满足的条件

主机必须运行 x86_64 架构的 Ubuntu 或 Debian,安装程序需要 root 权限。守护进程运行时仍保持 root 身份,因为它需要执行 loop 挂载并写入 cgroup。

沙箱通过带 gVisor 的 Docker 运行。gVisor 是一种容器运行时,会在容器内核与主机内核之间提供用户空间内核,并为每个沙箱提供 runsc 运行时。守护进程需要 Node 22 或更高版本。如果系统中的 Node 已是 22 或更高版本,安装程序会复用它;只有在 Node 缺失或版本较低时,安装程序才会下载固定版本,验证校验和,并将其解压到 /opt。

系统必须存在 swap,并且 vm.swappiness 必须为 100。这不是调优建议,而是功能要求。冻结沙箱时,系统会将空闲沙箱的内存移出到 swap;gVisor 将沙箱内存保存为共享内存,而内核在默认 swappiness 下不会交换共享内存。项目测试表明,默认值下回收的内存为 0 字节,而值为 100 时可回收 99.5 percent。请检查内核实际使用的值,因为某些云镜像会在一个你不会想到要读取的文件中设置 vm.swappiness = 0。

sysctl vm.swappiness
swapon --show

sysctl vm.swappiness 应输出 vm.swappiness = 100,而 swapon --show 应列出一个 swapfile。如果 swappiness 输出为 0,每次冻结都不会产生任何效果,你仍需为每个空闲沙箱支付完整的内存开销。

在 Ubuntu 上安装 Dormice

官方安装方式是将一个管道传递给 bash:

curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash

执行前先下载并阅读该脚本。此脚本以 root 身份运行,并会修改主机:如果未安装 Docker,则安装 Docker;下载并校验 gVisor 和 Caddy;如果主机没有 swap,则创建 swapfile;为 daemon、gateway 和镜像 registry 写入 systemd 单元;并添加防火墙规则。

curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh -o dormice-install.sh
less dormice-install.sh
sudo bash dormice-install.sh --swap-gb 8

--swap-gb 设置 swapfile 大小,默认值为 16。对于小型 VPS,这会占用过多磁盘空间。--mirror cn 将下载源切换为中国大陆可访问的镜像。重新运行安装程序会升级代码并修复配置漂移,但不会轮换 API token。

代码位于 /opt/dormice,配置位于 /etc/dormice/env(gateway 的配置还位于 /etc/dormice/gateway.env),sandbox 数据位于 /var/lib/dormice,dormice 和 dor 命令位于 /usr/local/bin。安装程序会在安装期间生成 API token,并以 mode 600 写入 /etc/dormice/env;同一个值也会写入 gateway 的文件。

没有可用于安装的带标签版本。截至 12 October 2026,该 repository 没有 git 标签,也没有 GitHub release。因此,安装程序会克隆 main,你得到的是当天早上最新提交的内容。要固定版本,必须记录实际安装的 commit。

git -C /opt/dormice rev-parse HEAD

将该 hash 与部署记录一同保存,因为它能准确说明你运行的是哪份代码。仅凭它无法回退:新进程启动时会执行数据库迁移,而升级文档说明,重新运行较旧的安装程序不会撤销迁移。重启任何服务前,安装程序会将两个数据库的快照保存到 /var/lib/dormice/backups/,并保留最近的三个快照。这些快照是升级失败后官方记录的回退方式,因此再次升级前,应先将最新快照复制到主机外部。

安装程序最后会运行 dor doctor。这是一个只读的主机检查,会启动真实的 gVisor 容器来验证运行时是否正常,而不是仅根据软件包列表作出判断。daemon 行为异常时,再次运行该检查。

sudo dor doctor
systemctl is-active dormice

systemctl is-active dormice 应输出 active。如果输出 failed,journalctl -u dormice -n 50 中会记录原因。启动失败通常是 swap 或 gVisor 前置条件未满足,而不是 daemon 本身的问题。

安装程序还会在主机上安装 Caddy,因此在确认防火墙配置完成前,先检查当前有哪些服务正在监听。

sudo ss -lntp

daemon 始终绑定到 127.0.0.1,设计上没有配置项可以修改该地址。只有端口可以更改:DORMICE_PORT 默认值为 3676。旁边的 gateway 也遵循相同规则,绑定到 127.0.0.1:3677;端口使用 DORMICE_GATEWAY_PORT,并且有意不提供主机地址配置。从笔记本访问其中任一服务都必须明确配置访问路径;最简单的方式是使用 SSH 隧道转发两个端口。

ssh -L 3676:127.0.0.1:3676 -L 3677:127.0.0.1:3677 root@your-server

隧道建立后,笔记本上的 http://127.0.0.1:3677/console 是 Web 控制台,由 gateway 提供服务。首次访问时,粘贴一次 API token 以证明你是操作员,然后设置控制台用户名和密码。登录后会设置一个有效期为 7 天的 httpOnly 会话 cookie,页面 JavaScript 无法读取该 cookie,控制台也不会再次显示 token。控制台中的 Connect 页面会输出可直接复制粘贴的客户端代码片段,并自动指向你自己的 endpoint。

创建沙箱并在其中执行代码

一个操作用于创建沙箱:acquire。该操作具有幂等性,因此相同的 key 始终返回同一个沙箱,并在需要时创建、唤醒、启动或恢复该沙箱。对于从未见过的 key,其他所有动词都会返回 404。dor CLI 没有 acquire 动词,因此第一个沙箱需要通过控制台或客户端库创建。

使用控制台最快。通过隧道打开 /console,并创建名为 my-agent 的沙箱。随后即可使用 CLI 操作它。

sudo grep DORMICE_API_TOKEN /etc/dormice/env
export DORMICE_ENDPOINT=http://127.0.0.1:3676
export DORMICE_API_TOKEN=paste-the-value-here
dor sandbox ls
dor sandbox exec my-agent 'python3 --version'

dor sandbox ls 会列出每个沙箱及其生命周期状态,因此可以据此监控沙箱从 active 变为 frozen。dor sandbox exec 会输出 Python 3.12 版本,因为默认镜像是 Ubuntu 24.04,并且已预装 Python 3.12、Node 24、git 和 ripgrep。如果出现 authentication error,则表示复制的 token 行中包含了变量名。

使用 dor sandbox push my-agent ./script.py 传输文件,文件会保存到 /home/user/script.py;使用 dor sandbox pull my-agent notes.txt 可将文件取回。本地文件动词对单个文件的大小限制为 16 MiB,而 E2B 文件接口支持流式传输,唯一限制是沙箱磁盘配额。

只有销毁操作会丢失数据。dor sandbox destroy my-agent 会删除沙箱,并且具有幂等性;主 README、内置 agent skill 和 CLI package README 都使用这一个名称记录了该操作。即使如此,也请在自己的构建中运行 dor sandbox --help,因为安装程序跟踪 main,而 CLI 仍在持续扩展。

让现有的 E2B 代码连接到您自己的服务器

这就是需要关注它的原因。npm 官方的 e2b 软件包未经修改即可与 Dormice 通信。在 SSH 隧道已打开的情况下,从您的笔记本电脑运行以下命令,这样服务器上不会有新的监听服务。

npm init -y
npm i e2b tsx
import { Sandbox } from 'e2b';

const sbx = await Sandbox.create({
  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
  apiUrl: 'http://127.0.0.1:3676/e2b/api',
  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
});

const result = await sbx.commands.run('python3 -c "print(6 * 7)"');
console.log(result.exitCode, result.stdout);

await sbx.kill();
DORMICE_API_TOKEN=paste-the-value-here npx tsx index.ts

正常运行时会输出退出代码 0 和 42。API 密钥是您的 Dormice 令牌,前面加上 e2b_ 前缀。这是兼容层要求的格式。

该兼容层不是存根实现。项目的端到端测试套件会通过官方软件包,针对真实的 Docker 和 gVisor daemon,测试流式 stdout 和 stderr、后台命令、交互式 PTY、签名的上传和下载 URL、目录监控以及端口代理。在迁移任何实际业务前,需要注意以下差异:

  • 尚未实现模板构建。模板是您自行构建并通过 dor template add 注册的 Docker 镜像,Sandbox.create('name') 会解析该镜像。未注册的名称会返回 404,而不是模拟成功。
  • 通过 E2B 接口创建的沙盒会获得实际的截止时间,因为 E2B 语义要求这样做。通过原生 API 创建的沙盒永远不会被强制设置截止时间。
  • 冻结的沙盒会保留其中的进程,并从暂停位置继续运行。因此,这里的暂停和恢复并不是您可能熟悉的停止后冷启动。

沙箱能阻止什么,以及不能阻止什么

gVisor 在用户空间拦截容器的系统调用,并自行处理这些调用,因此沙箱中的代码不会直接与主机内核通信。在沙箱内,命令以 user(uid 1000)运行,但该账户可以免密码使用 sudo,因此任何提出请求的代码都可以在沙箱内获得 root 权限。不要将 uid 视为防护措施:项目明确说明,安全边界是 gVisor,而不是 uid;即使沙箱内的代码提升了权限,仍然无法访问主机内核。这足以应对常见情况:生成的脚本运行 rm -rf /、写满磁盘,或不断 fork 直到某个进程终止时,只会破坏自身的沙箱,影响不会超出该沙箱。

以下情况无法由它阻止。你必须自行处理。

  • 沙箱可以正常访问出站网络。生成的代码可以下载任意内容,也可以发送它找到的任意内容。安装程序的网络加固只处理两项:将容器到云元数据服务的流量丢弃到 169.254.0.0/16 和 100.100.100.200;后者是 Alibaba Cloud 使用的地址。云服务会通过该服务向任何能够访问它的进程提供实例凭据。安装程序还会在 Docker 的 daemon.json 中使用 "icc": false 关闭容器之间的流量。除此之外,不会阻止其他流量。阅读 sudo iptables -S DOCKER-USER,并为沙箱不应访问的私有地址段添加自己的 DROP 规则。
  • Docker 会将自己的规则插入防火墙规则之前,因此已发布的容器端口可能可以从互联网访问,即使 ufw 声称该端口已关闭。在此主机上暴露任何端口前,请阅读 Docker 如何绕过 ufw 发布端口 和 VPS 的 ufw 防火墙基础。
  • gVisor 是用户空间内核,不是 hypervisor。这是有意的取舍,因为冻结要求沙箱以进程形式运行,而要求 KVM 会导致该程序无法安装在所有环境中。如果你的威胁模型要求硬件虚拟化,请使用 Firecracker 类的隔离方案,并接受由此带来的运维成本。
  • API token 是客户端侧的完整安全边界。任何持有 DORMICE_API_TOKEN 的主体都可以在该机器上创建、读取和销毁所有沙箱。为 agent 进程分配独立的 VPS 上的最小权限用户,并按照保护 SSH key 的方式保护该 token。在 VPS 上安全运行 Claude Code 中的做法同样适用。

daemon 本身以 root 身份在主机上运行。gVisor 保护主机免受沙箱内代码的影响,但没有任何机制可以保护主机免受 daemon 或 token 持有者的影响。因此,运行 Dormice 的机器应只运行这一项服务。如果你的 agent 还通过 MCP(model context protocol)访问工具,也应基于同样的原因,将这些工具部署在 独立的 VPS 上运行 MCP server。

4 GB 和 8 GB 能容纳多少个沙箱?

有两项会占用内存:主机自身的基础开销,以及当前处于唤醒状态的每个沙箱的工作集。为 Ubuntu、Docker 和 daemon 预留约 1 GB,然后用剩余内存除以一个沙箱实际使用的内存。运行读取少量文件的 Python 脚本时,一个沙箱通常占用约 200 到 300 MiB。运行编译器或完整测试套件时,一个沙箱可能超过 1 gibibyte。

图表Concurrent sandboxes by host RAM, arithmetic after a 1 GB host reserve
此图表背后的数据
[
  {
    "host": "4 GB VPS",
    "active_at_512_mib": 6,
    "active_at_1_gib": 3,
    "frozen_on_16gb_swap": 16
  },
  {
    "host": "8 GB VPS",
    "active_at_512_mib": 14,
    "active_at_1_gib": 7,
    "frozen_on_16gb_swap": 16
  }
]

如果每个沙箱使用 512 MiB,4 GB VPS 可同时唤醒约 6 个沙箱;如果每个沙箱使用完整的 1 gibibyte,则约为 3 个。8 GB VPS 对应的数量为 14 和 7。这些数值是并发工作的上限,只是算术结果,不是基准测试结果,因此应在自身负载运行期间监控 free -m。

冻结的沙箱受 swap 限制,而不是受 RAM 限制,这正是该设计的目的。一个曾占用 1 gibibyte 的冻结沙箱会在 swap 中保留大致相同的数据,但几乎不占用常驻内存,因此安装程序默认创建的 16 GB swapfile 大约可以容纳 16 个冻结沙箱。超过这个数量后,它们需要进入已停止状态,此时只占用磁盘空间。磁盘才是这里长期运行的实际限制:每个沙箱都会保留自己的文件系统,几十个各自包含 node_modules 目录的 agent 会在内存问题变得突出之前,先填满小容量卷。

冻结、停止、归档:生命周期设置

默认行为是空闲 10 分钟后冻结,3 天后停止;配置归档后,7 天后归档。将 stopAfterSeconds 设置为 null 可获得常驻 agent:它空闲时可能冻结,但不会冷启动。

归档是可选功能,daemon 会明确反映配置状态。在控制台的设置页面配置兼容 S3 的存储后(四个 DORMICE_S3_* 变量仍然存在,但仅作为 gateway 首次启动时使用的初始值),已停止 sandbox 的磁盘会使用 tar 和 zstd 打包,上传到 bucket,并在本地释放。该 bucket 可以是您在另一台机器上自行托管的 MinIO bucket。如果未配置存储,sandbox 会永久保持 stopped 状态;要求归档的策略会被拒绝,而不是被静默忽略。恢复过程也会明确显示,而不是静默执行:下一次 acquire 会立即返回 restoring 状态和进度值,磁盘恢复后再切换为 ready。

现在可以依赖它吗?

直说:对于任何无法重建的内容,都不建议依赖。该代码仓库创建于 8 July 2026。截至 12 October 2026,它有 1,509 个 stars、109 个 forks,采用 Apache-2.0 许可证,但完全没有 tagged release。README 中的状态说明也明确表示,目前没有任何内容可用于生产环境。

这种组合会带来明确的风险。安装程序跟踪 main,因此代码可能随时变化。接口也仍在调整:文档现在描述的是一个位于 daemon 前面的 gateway,它有自己的端口、配置文件和数据库。一个创建约 3 个月的项目也可能直接停止维护,因为许可证条款没有要求任何人继续开发。

E2B 兼容性使这种风险仍然可控。您的应用通过一个背后有托管实现的协议进行通信,因此如果 Dormice 停止维护,只需修改 2 个 URL 即可继续运行。让 agent 针对 E2B 接口而不是原生 API 开发,就能保留这个退出路径。原生 @dormice/sdk package 目前也尚未发布到 npm,因此使用它需要从代码仓库构建,这是优先采用兼容路径的第二个原因。

请在能够承受其丢失的环境中运行它。使用脚本重建主机,确保 token 不出现在任何提示符或 commit 中,并按照您自己的备份计划,将任何需要保留的数据移出 sandbox。

FAQ

Dormice 是否适合用于生产环境?

不适合,项目本身也明确说明了这一点。README 的状态行指出,目前其中没有任何内容可用于生产环境。截至 2026 年 10 月 12 日,该仓库创建约三个月,没有 git 标签,也没有发布版本,因此没有可固定的版本号。安装程序会克隆 main 分支,这意味着每次运行都会获取最新提交。每次安装后记录 git -C /opt/dormice rev-parse HEAD,保留安装程序写入 /var/lib/dormice/backups/ 的数据库快照副本,并将所有重要数据放在沙箱之外。

Dormice 与为 agent 提供一次性 VM 有什么区别?

一次性 VM 是一台带有 SSH 的计算机。您为一个会话创建它,之后再删除。Dormice 是一个执行 API:您的程序调用 acquire,然后调用 exec,直接获取标准输出和退出码,中间没有 shell 会话。VM 适合需要暂时使用完整计算机的人或 agent。Dormice 适合每天多次运行生成代码、且不希望每次运行都承担整台机器的配置和销毁开销的应用程序。

官方 E2B SDK 确实无需修改代码即可工作吗?

可以,但需要修改配置。将 apiUrl 和 sandboxUrl 指向 daemon 上的 /e2b/api 和 /e2b/envd,并在 API key 中使用带有 e2b_ 前缀的 Dormice token。命令执行、PTY 会话、文件传输、签名 URL 和端口代理都已由项目通过官方包运行端到端测试。模板构建是主要缺口:尚未实现 e2b template build,因此模板就是您构建并通过 dor template add 注册的 docker image。

4 GB VPS 可以运行多少个沙箱?

如果每个沙箱使用 512 MiB,在为操作系统、Docker 和 daemon 预留约 1 GB 后,同时保持唤醒的沙箱数量约为 6;如果每个沙箱使用完整的 1 GiB,则约为 3。冻结的沙箱受 swap 容量限制。因此,安装程序默认创建的 16 GB swapfile 可容纳约 16 个曾使用 1 GiB 内存的沙箱。请在实际负载下使用 free -m 测量您自己的环境,因为运行测试套件的沙箱所需资源可能是运行小型脚本的沙箱的数倍。

为什么 Dormice 要求将 vm.swappiness 设置为 100?

冻结沙箱意味着将其空闲内存移出到 swap。gVisor 将沙箱内存作为共享内存管理,而 Linux 内核在默认 swappiness 下不会交换共享内存。因此,在默认值下,冻结不会回收任何内存,沙箱仍会持续占用完整内存。项目测得默认值下回收的内存为 0 bytes,而设置为 100 时回收率为 99.5 percent。请使用 sysctl vm.swappiness 检查生效值,不要只读取配置文件,因为某些云镜像会将该值设为 0。

这篇文章对您有帮助吗?