BitMiracle-AI/Dormice

Dormice – “代理沙盒界的 SQLite”

它是什么

• Dormice 是一个专为 AI 代理设计的自托管沙盒平台。它让您能在单台机器或机器集群上运行多个隔离的执行环境（沙盒），而无需支付按秒计费的费用。沙盒是永久的：它们保留在主机上，且闲置时间越长，成本越低。

对 AI 的重要性

• 现代基于 LLM 的代理通常需要一个地方来执行代码、存储文件并在调用之间保持状态。公共沙盒服务（例如 E2B）会针对沙盒存在的每一秒收费，这迫使开发者将其视为抛弃式资源。Dormify 翻转了该模式：您拥有硬件，沙盒永久存在，且闲置沙盒几乎不消耗资源（冻结后仅占用几 MB 的 RAM）。

核心概念

• acquireSandbox(userKey) – 您唯一需要考虑的操作。它是幂等的：相同的 key 总是返回相同的沙盒，若不存在则创建，若已冻结则唤醒，若有需要则从归档中恢复。
• 生命周期状态 – active → frozen → stopped → archived。每个步骤都会减少资源使用；冻结的沙盒可在约 50 ms 内恢复，归档的沙盒则存储在 S3 并按需恢复。
• 单一二进制部署 – 一个守护程序（Fastify + SQLite 账本）加上一个可选的网页控制台网关。无需 Kubernetes、外部数据库或复杂的编排。
• E2B 兼容 API – 该守护程序在两个 URL 前缀上实现了 E2B 协议，因此使用官方 e2b SDK 的现有代码只需更改 URL 和 token 即可运行。

关键组件 (monorepo 布局)

软件包	角色
packages/server	核心守护程序：HTTP API、SQLite 账本、生命周期引擎
packages/gateway	集群入口，存储设置/模板，提供网页控制台
packages/sdk	原生 TypeScript 客户端 (@dormify/sdk)
packages/cli	用于操作员的 dor 命令行工具
packages/console	用于通过浏览器管理沙盒的 React SPA
e2e	使用真实 e2b SDK 驱动守护程序的黑盒端到端测试套件
examples	可直接运行的演示（原生 SDK、官方 e2b SDK、常驻代理）

安装 (一行指令)

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

• 适用于裸机 Ubuntu/Debian x86_64 主机（以 root 执行）。脚本会安装 Docker、gVisor (runsc)、zstd，设置 swap 并写入 systemd 服务。
• 安装程序是幂等的：重新执行会升级代码并使用 dor doctor 验证安装。
• 将第二个节点加入同一个集群只需一个额外指令 (--role node --gateway http://<first>:80)。

快速使用 (TypeScript SDK)

import { Dormice } from '@dormice/sdk';
const client = new Dormice({ endpoint: 'http://127.0.0.1:3677', token: process.env.DORMICE_API_TOKEN! });
await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
const res = await client.execCommand('my-agent', 'python3 -c "print(6*7)"');
console.log(res.exitCode, res.stdout); // 0 42
await client.writeFiles('my-agent', [{ path: 'notes.txt', content: 'survives freeze and stop' }]);
await client.destroySandbox('my-agent');

• 同样的操作可通过 curl 或 dor CLI (dor sandbox ls, dor exec, dor push, …) 执行。

E2B 兼容性

• 守护程序在 /e2b/api 和 /e2b/envd 下公开 E2B API。使用官方 e2b npm 软件包的现有代码可指向：

apiUrl: 'http://127.0.0.1:3677/e2b/api',
sandboxUrl: 'http://127.0.0.1:3677/e2b/envd',
apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`

• 支持所有主要的 E2B 表面功能（沙盒创建、暂停/恢复、流式 I/O 指令执行、PTY、文件操作、签名上传/下载 URL、目录监控、端口代理、指标）。部分高级功能（模板构建、xattr 元数据）刻意未实现并会返回明确的 unimplemented 错误。

网页控制台

• 登录 API token（仅存储为 httpOnly cookie）后，可于 http://127.0.0.1:3677/console 访问。
• 显示实时沙盒状态，让您创建/获取、销毁、推送/拉取文件，并提供 SDK、CLI 或 E2B 客户端的复制粘贴代码片段。
• 旨在通过 SSH 通道或反向代理（提供 Caddy 示例）在本地访问。流式输出仅在使用禁用缓冲的代理（flush_interval -1）时有效。

冷归档 (选用 S3 存储)

• 设置 DORMICE_S3_* 环境变量后，已停止一段可配置时间的沙盒会被 tar-zstd 压缩并上传至 S3 兼容存储桶。
• 下次执行 acquireSandbox 时，守护程序会返回 restoring 状态并流式传输进度，直到归档下载并解压缩完成。
• 若未设置 S3，沙盒会停在 stopped 状态且永不归档。

何时不该使用 Dormice

• 您需要能在机器或区域间迁移的沙盒 – Dormice 将沙盒绑定到创建它的节点。
• 您偏好具有 SLA 的全托管 SaaS 服务 – 那是托管的 E2B 产品。
• 您的安全模型需要硬件级隔离 (KVM/Firecracker)。Dormice 使用 Docker + gVisor (用户空间内核) 来实现快速冻结。
• 您的工作负载是非 Linux 的（例如 Windows 二进制文件）。

开发工作流程

pnpm install
pnpm build      # 构建守护程序、SDK、CLI、控制台
pnpm typecheck
pnpm lint
pnpm test        # 针对构建的守护程序运行 e2e 套件

• 仓库使用 pnpm monorepo；所有软件包共享来自 packages/shared 的协议结构 (zod)。

贡献模型

• 核心团队维护代码；外部贡献者可以提交 issue，但不接受 pull request。此政策旨在保护已在生产环境中运行的集群稳定性。

授权

• Apache-2.0。

---

总结：Dormice 为需要持久状态和低闲置成本的 AI 代理提供了低成本、自托管的沙盒环境。它模仿 E2B API，因此现有的代理代码只需极小的变更即可切换到自有平台，同时为人类操作员提供网页 UI 和 CLI。