Dormice: A Self-Hosted E2B-Compatible Agent Sandbox Platform with Permanent Sandbox Lifecycle

The Problem Dormice Solves: Permanent Sandboxes vs. Disposable Billing

Cloud sandbox platforms such as the hosted E2B service bill for every second a sandbox exists, which encourages short-lived, disposable sandboxes. Agents that need persistent state across multiple sessions must rebuild context from scratch each time or store and reload state externally. Dormice inverts this model by running on hardware the operator already pays for, making sandboxes permanent by default.

The central abstraction is acquireSandbox(userKey): idempotent, keyed by a string. The same key always returns the same sandbox regardless of what state it was in. If the sandbox does not exist it is created; if it is frozen it wakes; if it is stopped it starts; if it is archived it is restored. No sandbox management logic is required in the calling code.

Idle sandboxes cool down automatically through four states: active, frozen, stopped, and archived. Each cooling step reduces resource consumption. The README gives a measurement from real hardware: freezing takes an idle sandbox holding 1 GiB of resident memory down to approximately 5 MiB, and waking a frozen sandbox takes approximately 50 ms. This makes the permanently-resident agent model practical: the sandbox does not need to be rebuilt from scratch when the agent resumes.

Installing Dormice on a Bare Server

The installer runs as root on a bare Ubuntu or Debian x86_64 host with a single command:

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

Behind a slow connection to the default package sources, adding -s -- --mirror cn uses a mirror. The README states the installer is idempotent: re-running it upgrades the code, repairs configuration drift, and never rotates the API token. The installer ends by running dor doctor, a battery of read-only checks including three checks that boot a real gVisor container, to verify that the installation succeeded. The dor doctor command can be run independently at any time as a health check.

A second machine joins the same fleet with one additional command using --role node --gateway http://[first machine]:80 with the API token in the environment. Node machines require no further configuration; upgrades propagate from the gateway one node at a time. The daemon runs on a single port, uses a single SQLite ledger for state, and requires no external database or Kubernetes.

The Native TypeScript SDK and Wire Protocol

The native client for Dormice is @dormice/sdk, a TypeScript package. The README notes it is not yet on npm; the first release is queued and the package can be built from source with pnpm build inside the repository. The central API call demonstrates the lifecycle model:

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 result = await client.execCommand('my-agent', 'python3 -c "print(6 * 7)"');
console.log(result.exitCode, result.stdout); // 0 42

The policy stopAfterSeconds: null makes a sandbox a resident agent: it may freeze when idle but never cold-starts. The wire protocol is plain HTTP RPC (POST /acquireSandbox, POST /execCommand, and others), so curl works wherever the SDK does not. The dor CLI covers operator tasks: dor sandbox ls, exec, push, pull, rebuild, destroy, and dor doctor.

E2B Compatibility: What Works and Where It Differs

Dormice speaks the E2B protocol on two prefixes: /e2b/api and /e2b/envd. Migrating an application from hosted E2B to Dormice requires changing two configuration values:

import { Sandbox } from 'e2b';

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

The README lists the E2B surface that has been exercised through the official package against a real Docker and gVisor daemon: Sandbox.create, connect, kill, list, pause and resume, commands.run with streaming and background execution, pty operations, file read and write, uploadUrl and downloadUrl with signed URLs, directory listing and watching, and getHost for port proxying with wake-on-traffic.

Deliberate differences from the hosted product: Dormice does not implement the E2B template build pipeline; templates are named Docker images registered with dor template add. Frozen sandboxes in Dormice suspend processes mid-flight rather than discarding them, so the sandbox resumes exactly where it paused. Natively created sandboxes are permanent by default and never have deadlines imposed on them.

Where Dormice Is Not Ready Yet

The README opens with an explicit status warning: early development. The create, freeze, stop, archive, and restore cycle works end to end, but nothing is production-ready. The README says this directly without qualification.

The @dormice/sdk package is not yet published to npm. Teams cannot add it as a dependency via a standard package install today; they must clone the repository and build it locally. The first npm release is described as queued.

E2B compatibility covers the main surface but with documented gaps. Template builds using e2b template build are not implemented: users must build Docker images themselves and register them with dor template add. Teams who depend on E2B's cloud build pipeline for template creation will need to replace that step with a local Docker build.

The single SQLite ledger means that the gateway node is a single point of state. The README does not document a high-availability configuration or a procedure for recovering from gateway node failure while preserving sandbox state.

License and Agent Skill Documentation

Dormice is licensed under Apache-2.0, which permits commercial use and modification without copyleft requirements. The last push to the main branch was on 2026-09-18. The repository has no GitHub releases yet.

Beyond the TypeScript SDK, Dormice ships an agent skill in the open Agent Skills format, installable with:

npx skills add BitMiracle-AI/Dormice

The skill at skills/dormice/SKILL.md teaches a coding agent the full operator surface: how to connect, choose between the E2B SDKs, the native API, or the CLI, run commands, move files, and set lifecycle policy. The documentation site also emits /llms.txt, /llms-full.txt, and a plain-markdown version of every docs page for AI consumption.

The repository layout separates concerns clearly: packages/ holds the SDK and daemon code, examples/ holds runnable demonstrations, deploy/ holds the installer, website/ holds the documentation source, and skills/ holds the agent skill. The e2e/ directory covers the black-box end-to-end test suite that runs through the official e2b package against the real daemon, which is the verification basis for the E2B compatibility table in the README.

Editorial conclusion

Teams building AI agent workflows who want to avoid per-second cloud sandbox billing and are willing to manage their own server will find Dormice's permanent lifecycle model and E2B compatibility worth evaluating. The README is explicit that the project is in early development and nothing is ready for production yet. Migrating from the hosted E2B service to Dormice is documented as a configuration change, not a code change, which lowers the switching cost for teams already using the e2b SDK. A production deployment requires a stable Ubuntu/Debian x86_64 host with Docker and gVisor installed, and the daemon uses a single SQLite ledger as its state store.

Frequently asked questions

Official sources

1. BitMiracle-AI/Dormice on GitHub
2. Issues
3. License: Apache-2.0
4. README