Dormice: a self-hosted, E2B-compatible sandbox daemon that freezes idle agents

The billing model Dormice is built against

Hosted sandbox platforms bill for wall-clock existence, which pushes users toward short-lived, disposable sandboxes. Dormice takes the opposite position: run the daemon on hardware you already pay for, and let a sandbox persist indefinitely while becoming cheaper to hold. The README describes the state ladder as active, then frozen, then stopped, then archived, with each transition happening one rung at a time as the sandbox sits idle, and any acquire call pulling it back. The audience is narrow and specific. It is not for teams who want a managed control plane. It is for someone with a machine, a token budget measured in electricity, and agents that need a stable home directory across weeks rather than a fresh container per request.

acquireSandbox as the only verb that matters

The native mental model is a single idempotent call. acquireSandbox(userKey) returns the same sandbox for the same key regardless of what state that sandbox is in: if none exists it creates one, if frozen it wakes it, if stopped it starts it, if archived it restores it. That collapses four lifecycle operations into one entry point and removes the need for callers to track state themselves. The README's example passes a policy object with stopAfterSeconds set to null, which it describes as making the sandbox a resident agent: it may freeze when idle, roughly 50 ms to wake according to the project's own measurements on real hardware, but it will never cold-start. Destroy is called out as the only verb that loses data. Note the shape of that claim. Freezing preserves running processes and resumes them mid-flight, and file writes survive freeze and stop. The lifecycle is therefore not a snapshot-and-restore of a container image in the usual sense; it is a suspension of the running thing. The README states that freezing an idle sandbox holding 1 GiB brings it to about 5 MiB of resident memory. Those numbers come from the project, not from independent measurement.

What the executor and the ledger actually consist of

The daemon executes sandboxes with Docker plus gVisor, and the README lists the real executor alongside the lifecycle engine, SDK, CLI, web console, S3 archiver and E2B-compatible API as components that work end to end. Persistence is a single SQLite ledger rather than an external database, and the whole thing is one daemon on one port. That is the architectural bet: no Kubernetes, no separate state store, no coordination layer. The S3 archiver is what the archived rung of the ladder writes to, which means the cheapest idle state depends on object storage being reachable when a sandbox needs to come back. The README does not describe what happens to an archived sandbox when the archiver's target is unavailable, and that is a gap worth probing before trusting the ladder in an unattended deployment. The wire protocol is plain HTTP RPC on paths like POST /acquireSandbox and POST /execCommand, so curl reaches anything the SDK does not.

Installing it, and what dor doctor checks

The documented install is a single command on a bare Ubuntu or Debian x86_64 host, run as root: curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash. Behind a slow connection to the usual sources, the README says to add -s -- --mirror cn. The installer is described as idempotent: re-running it upgrades the code, repairs drift, and never rotates your API token. It finishes by running dor doctor, a set of read-only checks, three of which boot a real gVisor container, and that run decides whether the install succeeded. dor doctor can be re-run on its own at any time. The native client is @dormice/sdk, constructed with an endpoint such as http://127.0.0.1:3676 and a token read from DORMICE_API_TOKEN. The README states plainly that the package is not on npm yet and that pnpm build inside the repository produces it. The operator CLI covers dor sandbox ls, exec, push, pull, rebuild and destroy. One environment variable appears in the compatibility table: DORMICE_SANDBOX_DOMAIN, which the README ties to getHost(port) and its wake-on-traffic behaviour.

Pointing the official e2b package at your own machine

Dormice serves the E2B protocol on two prefixes, /e2b/api and /e2b/envd. The migration the README shows is configuration rather than code: pass apiUrl as http://127.0.0.1:3676/e2b/api, sandboxUrl as http://127.0.0.1:3676/e2b/envd, and an apiKey of e2b_ prefixed with your DORMICE_API_TOKEN. The compatibility table covers commands.run with live stdout and stderr streaming, background commands, sendStdin and kill, a real interactive bash over pty, streamed file reads and writes with no artificial size cap beyond the disk quota, signed uploadUrl and downloadUrl with expiry enforced and tampered signatures rejected as 401, files.watchDir including the polling watcher the Python sync SDK uses, and getMetrics returning one live sample without waking a frozen sandbox. The README says these surfaces are exercised by a black-box e2e suite running through the official package against a real Docker plus gVisor daemon. There are deliberate divergences. Template builds are absent: a template is a named image you build with docker and register via dor template add, and an unregistered name returns a 404. Sandboxes created through the E2B surface get real deadlines because E2B semantics demand them, while natively created sandboxes never do. metadata.externalId maps Sandbox.create onto the idempotent acquire. Unimplemented endpoints answer with an honest unimplemented on the wire, which is a better failure mode than a silent no-op, though the README's list of what falls into that category is truncated in the material available.

Where Dormice is the wrong tool

The README's own status line is the first limitation and the largest: the daemon, lifecycle engine, SDK, CLI, web console, executor, archiver and E2B API work end to end, and nothing is ready for production. Treat that as the governing constraint rather than a disclaimer to read past. The second limitation is the missing template build pipeline. If your workflow depends on e2b template build producing images on the server, Dormice does not do it, and you replace that step with docker plus dor template add. The third is distribution: @dormice/sdk is not on npm, so native TypeScript consumers build from the repository, and the README notes no releases have been retrieved. The fourth is the deployment target itself. One bare Ubuntu or Debian x86_64 host as root is the documented path. There is no stated multi-node story, and the single SQLite ledger implies a single writer. If you need horizontal scale across machines, or you need sandboxes to be genuinely disposable and cheap to recreate, the permanence that Dormice sells as a feature becomes an operational liability you have to manage.

How this differs from E2B itself and from plain Docker

The obvious comparison is the hosted E2B product, and the difference is not the API surface because Dormice deliberately matches it. The difference is where state lives and who pays for idle time. On the hosted side, per-second billing makes sandboxes disposable, and the build pipeline is a server-side service. On Dormice, you supply the machine, idle sandboxes descend the ladder toward archived and object storage, and template builds move to your own docker commands. The second comparison is running containers directly. Plain docker gives you process isolation but no acquire-by-key idempotency, no freeze that preserves running processes, no signed file URLs, and no E2B protocol for an existing agent framework to speak. Dormice's value is the lifecycle contract plus the compatibility shim, not the container runtime, which is Docker and gVisor in both cases. If your agents are already written against the e2b package and you want them on hardware you control, the shim is the whole argument. If your agents are bespoke and you have no E2B dependency, you are adopting a young project to get acquireSandbox and the freeze ladder, and you should weigh that honestly.

Licence, upgrades, and the cost of staying current

Dormice is Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved, and it includes an express patent grant. That is a permissive arrangement, and this is a description of the licence text, not legal advice; if you are embedding the daemon in a product, have counsel read the NOTICE and attribution requirements rather than taking a summary from an article. On maintenance, the material supports only a limited picture. The repository is not archived and the last push shown is 2026-09-09. The installer is documented as idempotent and as the upgrade path: re-running it upgrades the code, repairs drift and preserves your API token. That means your upgrade cost is bounded by re-running one script and then re-running dor doctor, which the README says re-verifies the install including the three checks that boot a real gVisor container. What the material does not give you is a release cadence, a versioning policy, or a migration story for the SQLite ledger and the S3 archive format when the daemon changes. Those are the things to ask about before you put persistent agent state behind this.

Editorial conclusion

Adopt Dormice if you already pay for a single Ubuntu or Debian x86_64 host, you want the official e2b package to keep working, and you can tolerate a project whose own README says nothing is production-ready. Do not adopt it if you need hosted template builds, a published npm package today, or any support commitment. Verify first that dor doctor passes on your host, including the three checks that boot a real gVisor container, and confirm the daemon answers unimplemented rather than failing silently on the E2B calls your application makes.

Official sources

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