BitMiracle-AI/Dormice

Dormice – “SQLite of agent sandboxes”

What it is

• Dormice is a self‑hosted sandbox platform designed for AI agents. It lets you run many isolated execution environments (sandboxes) on a single machine—or a fleet of machines—without paying per‑second usage fees. Sandboxes are permanent: they stay on the host and become cheaper the longer they sit idle.

Why it matters for AI

• Modern LLM‑based agents often need a place to run code, store files, and keep state between calls. Public sandbox services (e.g., E2B) charge for every second a sandbox exists, which forces developers to treat them as disposable. Dormify flips that model: you own the hardware, the sandbox lives forever, and idle sandboxes consume almost no resources (they freeze to a few megabytes of RAM).

Core concepts

• acquireSandbox(userKey) – The only operation you need to think about. It is idempotent: the same key always returns the same sandbox, creating it if it doesn’t exist, waking it if it’s frozen, or restoring it from archive if needed.
• Lifecycle states – active → frozen → stopped → archived. Each step reduces resource usage; a frozen sandbox can be resumed in ~50 ms, and an archived one is stored in S3 and restored on demand.
• Single‑binary deployment – One daemon (Fastify + SQLite ledger) plus an optional gateway for a web console. No Kubernetes, external DB, or complex orchestration required.
• E2B‑compatible API – The daemon implements the E2B protocol on two URL prefixes, so existing code that uses the official e2b SDK works with only a URL and token change.

Key components (monorepo layout)

Package	Role
packages/server	The core daemon: HTTP API, SQLite ledger, lifecycle engine
packages/gateway	Front‑door for a fleet, stores settings/templates, serves the web console
packages/sdk	Native TypeScript client (@dormify/sdk)
packages/cli	dor command‑line tool for operators
packages/console	React SPA for managing sandboxes via a browser
e2e	Black‑box end‑to‑end test suite that drives the daemon with the real e2b SDK
examples	Ready‑to‑run demos (native SDK, official e2b SDK, resident agent)

Installation (one‑liner)

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

• Works on a bare Ubuntu/Debian x86_64 host (run as root). The script installs Docker, gVisor (runsc), zstd, sets up swap, and writes a systemd service.
• The installer is idempotent: re‑running upgrades the code and validates the installation with dor doctor.
• Adding a second node to the same fleet is a single extra command (--role node --gateway http://<first>:80).

Quick usage (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');

• The same actions can be performed with curl or the dor CLI (dor sandbox ls, dor exec, dor push, …).

E2B compatibility

• The daemon exposes the E2B API under /e2b/api and /e2b/envd. Existing code that uses the official e2b npm package can point to:

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}`

• All major E2B surface features are supported (sandbox creation, pause/resume, command execution with streaming I/O, PTY, file operations, signed upload/download URLs, directory watching, port proxy, metrics). Some advanced features (template builds, xattr metadata) are deliberately unimplemented and return an explicit unimplemented error.

Web console

• Accessible at http://127.0.0.1:3677/console after logging in with the API token (stored only as an httpOnly cookie).
• Shows live sandbox state, lets you create/acquire, destroy, push/pull files, and provides copy‑paste snippets for the SDK, CLI, or E2B client.
• Intended to be accessed locally via SSH tunnel or via a reverse proxy (Caddy example provided). Streaming output works only with a proxy that disables buffering (flush_interval -1).

Cold archive (optional S3 storage)

• When DORMICE_S3_* environment variables are set, sandboxes that have been stopped for a configurable period are tar‑zstd‑compressed and uploaded to an S3‑compatible bucket.
• On the next acquireSandbox, the daemon returns a restoring status and streams progress until the archive is downloaded and unpacked.
• If S3 is not configured, sandboxes stop at the stopped state and never archive.

When not to use Dormice

• You need sandboxes that migrate across machines or regions – Dormice ties a sandbox to the node where it was created.
• You prefer a fully managed SaaS offering with SLAs – that’s the hosted E2B product.
• Your security model requires hardware‑level isolation (KVM/Firecracker). Dormice uses Docker + gVisor (userspace kernel) to enable fast freezing.
• Your workloads are non‑Linux (e.g., Windows binaries).

Development workflow

pnpm install
pnpm build      # builds daemon, SDK, CLI, console
pnpm typecheck
pnpm lint
pnpm test        # runs the e2e suite against the built daemon

• The repository uses a pnpm monorepo; all packages share protocol schemas (zod) from packages/shared.

Contribution model

• The core team maintains the code; external contributors can file issues, but pull requests are not accepted. This policy protects the stability of fleets that already run in production.

License

• Apache‑2.0.

---

Bottom line: Dormice provides a low‑cost, self‑hosted sandbox environment tailored for AI agents that need persistent state and cheap idle time. It mimics the E2B API, so existing agent code can switch to a locally owned platform with minimal changes, while offering a web UI and CLI for human operators.