Dormice

环境要求

• Ubuntu/Debian x86_64 主机，需要 root 权限（loop mount、cgroup 写入）
• 已安装 Docker 与 gVisor（runsc）运行时
• 配置好 Swap 且 vm.swappiness=100
• daemon 自身可运行在任意 Node 22+ 环境（开发时可用内存假执行器）
• 主机需能访问 GitHub raw 内容以下载安装脚本

安装与启动步骤

1. 1确认主机条件

   在一台自己的 Ubuntu/Debian x86_64 机器上操作，准备 root 权限，并确认已装 Docker 与 gVisor(runsc)、已配置 swap。

2. 2一键安装

   以 root 在裸机上执行安装脚本；脚本幂等，重复运行会升级代码并修复偏差，且不会轮换 API token。

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

   复制

3. 3国内镜像安装

   若访问常用源较慢，在管道后追加 -s -- --mirror cn 参数，改用国内镜像加速下载。

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

   复制

4. 4运行自检

   安装结束时脚本会自动执行 dor doctor，这是一组只读检查，其中三项会启动真实 gVisor 容器来判断安装是否成功。

   dor doctor

   复制

5. 5用 CLI 管理沙箱

   dor CLI 负责运维侧操作，包含枚举、执行、推送、拉取、重建、销毁沙箱等子命令。

   dor sandbox ls

   复制

6. 6用 SDK 调用沙箱

   @dormice/sdk 是原生 TypeScript 客户端；用同一个 key 反复 acquire 即可复用同一沙箱。

   import { Dormice } from '@dormice/sdk';
   
   const client = new Dormice({
     endpoint: 'http://127.0.0.1:3676',
     token: process.env.DORMICE_API_TOKEN!,
   });
   
   await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
   
   const result = await client.execCommand('my-agent', 'python3 -c "print(6 * 7)"');
   console.log(result.exitCode, result.stdout);

   复制

关键配置

如何确认成功

dor doctor 全部通过（其中三项检查会真实启动 gVisor 容器）即表示安装成功，可随时单独重跑 dor doctor。

常见问题

注意事项

• sandbox 执行的是不受信任的代码，必须阻断容器访问云元数据服务（iptables -I DOCKER-USER -d 169.254.0.0/16 -j DROP）并禁用容器间通信。
• daemon 出于设计只绑定 127.0.0.1 且没有开关，如需对外暴露请自行用反向代理。
• 一台机器只能运行一个 daemon，daemon 会用账本旁的锁强制这一限制。
• 状态会沿 active → frozen → stopped → archived 逐级下降，任意 acquire 都能把沙箱唤醒，destroy 是唯一会丢数据的操作。