Dormice

The SQLite of agent sandboxes — a self-hosted sandbox platform for AI agents. One machine or a fleet of them, sandboxes that live forever, idle costs nothing.

Status: early development. The daemon, its lifecycle engine, the SDK, the CLI, the web console, the real Docker + gVisor executor, the S3 archiver, and the E2B-compatible API work end to end — the full create → freeze → stop → archive → restore cycle, command execution, file I/O, and the official e2b SDK against real infrastructure. Nothing here is ready for production yet.

The idea

Cloud sandbox platforms charge for every second a sandbox exists, so their sandboxes are disposable. Dormice inverts that: you run it on a machine you already pay for, and sandboxes are permanent — they just get cheaper to keep the longer they sit idle.

• acquireSandbox(userKey) is the entire mental model. Idempotent: the same key always comes back to the same sandbox, whatever state it was in. No sandbox → create; frozen → wake; stopped → start; archived → restore.
• Idle is free. Sandboxes cool down on their own — active → frozen → stopped → archived — one rung at a time, and any acquire brings them back. Measured on real hardware: freezing takes an idle sandbox holding 1 GiB down to ~5 MiB of resident memory, and waking it takes ~50 ms.
• Deploys like a single binary. One daemon, one SQLite ledger, one port. No Kubernetes, no external database.
• E2B compatible: the official e2b SDK works against Dormice by changing two URLs.

Install

One command on a bare Ubuntu/Debian x86_64 host (as root):

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

Behind a slow connection to the usual sources, add -s -- --mirror cn. The installer is idempotent — re-running it upgrades the code and repairs drift, and never rotates your API token. It ends by running dor doctor, a battery of read-only checks — three of them boot a real gVisor container — that decides whether the install actually succeeded; dor doctor can be re-run on its own at any time.

A second machine joins the same fleet with one more command (--role node --gateway http://<first machine>:80, the token in the environment) and needs no settings of its own; upgrades then run from the gateway, one node at a time. See the installation and upgrading docs.

Quick start

@dormice/sdk is the native TypeScript client. (Not on npm yet — the first release is queued; inside this repo, pnpm build produces it.)

import { Dormice } from '@dormice/sdk';

const client = new Dormice({
  endpoint: 'http://127.0.0.1:3677',
  token: process.env.DORMICE_API_TOKEN!,
});

// One key, one sandbox — created, woken or restarted as needed.
// stopAfterSeconds: null makes it a resident agent: it may freeze when
// idle (~50 ms to wake) but never cold-starts.
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

await client.writeFiles('my-agent', [
  { path: 'notes.txt', content: 'survives freeze and stop' },
]);

await client.destroySandbox('my-agent'); // destroy — the only verb that loses data

The wire is plain HTTP RPC (POST /acquireSandbox, POST /execCommand, …), so curl works where the SDK doesn't reach, and the dor CLI covers the operator side: dor sandbox ls / exec / push / pull / rebuild / destroy, plus dor doctor. The full native surface is documented in packages/sdk, and runnable versions of these flows live in examples/.

Agent skill

Dormice's users are agents, so the manual comes in a form an agent can install — a skill in the open Agent Skills format:

npx skills add BitMiracle-AI/Dormice

One file, skills/dormice/SKILL.md, teaching a coding agent the whole surface: how to connect, pick between the E2B SDKs / native API / CLI, run commands, move files, and set lifecycle policy. The documentation site is AI-readable too — its build emits /llms.txt, /llms-full.txt, and a plain-markdown .md twin of every docs page.

E2B compatibility

The daemon speaks the E2B protocol on two prefixes (/e2b/api, /e2b/envd). The official e2b package — unmodified, straight from npm — runs against Dormice with two URLs and an API-key prefix; migrating an application is configuration, not code:

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',
});

Everything below is exercised by the black-box e2e suite through the official package, and has passed against a real Docker + gVisor daemon:

This is the beginning of the README. Read the rest at the original. Read the full README ↗