Dormice

Dormice

Dormice is a self-hosted sandbox platform: a gateway (the front door — console, API keys, fleet settings) and one or more daemons (the nodes that run the sandboxes; a single machine runs both), and sandboxes that are permanent — idle ones cool down (active → frozen → stopped → archived) instead of being destroyed, and any acquire brings them back. Two facts drive every workflow below:

• acquireSandbox(name) is the entire mental model. Idempotent — the name is a unique address that never errors as a duplicate: the same name always returns the same sandbox, whatever state it was in. No sandbox → create; frozen → wake (~50 ms); stopped → start; archived → restore. Only acquireSandbox creates — other verbs answer 404 for an unknown name.
• The disk, not the container, is the sandbox's body. Files survive freezes, stops, daemon restarts, and host reboots. Only destroySandbox loses data.

Connecting

Two doors, both bound to 127.0.0.1 only: the gateway on 3677 (the console, templates, API keys, settings, and every per-sandbox verb, which it forwards to the node) and the daemon on 3676 (the sandbox verbs plus the list and observation verbs the gateway does not answer yet). On the server itself use those addresses directly; from another machine the operator has either an SSH tunnel (ssh -L 3677:127.0.0.1:3677 -L 3676:127.0.0.1:3676 root@host) or a reverse-proxy domain in front of the gateway (then use https://their-domain). Auth is one API token (created by the installer, hex): ask the user for the endpoint and token, conventionally held in DORMICE_ENDPOINT / DORMICE_API_TOKEN. API keys minted in the console (or with dor apikey create <name>) open the gateway wherever the token does — same variables, revocable per client — except the verbs that configure the fleet (keys, settings, templates, domains), which require the token (keys cannot manage keys); a daemon knows only the token.

Pick an entry path

Official E2B SDKs — change two URLs

The daemon speaks the E2B protocol on /e2b/api (control plane) and /e2b/envd (in-sandbox). Prefix the token with e2b_:

tsCopy 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',
});
await sbx.commands.run('echo hello');

pythonCopy code
import os
from e2b import Sandbox

sandbox = Sandbox.create(
    api_key=f"e2b_{os.environ['DORMICE_API_TOKEN']}",
    api_url="http://127.0.0.1:3677/e2b/api",
    sandbox_url="http://127.0.0.1:3677/e2b/envd",
)
sandbox.commands.run("echo hello")

Sandbox.create makes a fresh sandbox each time (faithful E2B semantics). To get Dormice's idempotent acquire through the E2B surface, pass metadata: { name: 'my-project' } — the same name then always returns the same sandbox with its files intact. E2B timeoutMs deadlines are real: at the deadline the sandbox is killed, or parked with lifecycle: { onTimeout: 'pause' } and revived by connect.

Native API — one POST route per verb

Every operation is POST /<sdkMethodName> with a JSON body and Authorization: Bearer <token>; every non-2xx body is { "message": "..." }. Core loop with the SDK:

tsCopy code
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

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

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

The same loop in curl:

shCopy code
curl -X POST http://127.0.0.1:3677/acquireSandbox \
  -H "Authorization: Bearer $DORMICE_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name": "my-agent"}'

Verbs: acquireSandbox (optionally with metadata — string-to-string labels stored at creation for grouping/filtering), updatePolicy (patch an existing sandbox's lifecycle policy in place — no wake, no destroy), updateMetadata (replace an existing sandbox's label set wholesale, {} clears — same no-wake manners), listSandboxes, execCommand, writeFiles / writeFile, readFile / readFiles, rebuildSandbox (fresh container, /home/user kept), destroySandbox, registerTemplate / listTemplates / removeTemplate (at the gateway; nodes learn a template at their next check-in), createApiKey / listApiKeys / updateApiKey / revokeApiKey (at the gateway: revocable peers of the API token with optional expiry and a reversible disable switch; the create response shows the key once, never again; these four verbs accept only the token), getHostMetrics (one machine's reading; at the gateway name the node with nodeId, a fleet of one needs none), getSandboxMetrics / listSandboxMetrics (live resource samples; never wake anything), listSandboxImages (who still runs an old template image) — the lists at the gateway are every node's, with silent naming a node it could not include — getFleetMetrics / getFleetStateHistory (the fleet's sums and its census over time, answered by the gateway from the nodes' check-ins), getConfig / updateSettings (the fleet's settings at the gateway, secrets redacted; applied by every node at its next check-in), getIngress / setIngress (bind domains on the gateway's managed reverse proxy), listNodes (every node and what it last reported). execCommand takes { name, command, timeoutSeconds?, cwd?, env? } and returns { exitCode, stdout, stderr, ... } — a non-zero exit code is a result, not an HTTP error. When a sandbox is coming back from S3, acquireSandbox returns { status: 'restoring', progress } immediately; poll it until the status flips to ready.

CLI

shCopy code
dor sandbox ls                        # every sandbox, with lifecycle state
dor sandbox exec my-agent 'uname -r'  # exit code passes through
dor sandbox push my-agent ./data.csv  # → /home/user/data.csv
dor sandbox pull my-agent notes.txt
dor sandbox rebuild my-agent          # fresh container, /home/user kept
dor sandbox meta my-agent app=crawler # replace labels (no args = show)
dor sandbox destroy my-agent
dor apikey create ci                  # mint a revocable key (printed once)
dor doctor                            # can this machine run sandboxes?

Connects via DORMICE_ENDPOINT and DORMICE_API_TOKEN.

Files

Native file verbs move content as base64 inside JSON, capped at 16 MiB per file (batches 48 MiB) with honest refusals — never a truncated file. Paths are absolute or relative to /home/user; parent directories are created. Past the cap: download from inside the sandbox (execCommand with curl, in the stock image), or use the E2B files surface (files.read/write stream uncapped; uploadUrl() / downloadUrl() mint signed URLs).

Lifecycle policy — three knobs

Set at creation (overrides while acquiring an existing sandbox are not applied — change an existing sandbox's policy with updatePolicy, a patch that never wakes and never resets the idle clock); all count seconds since last activity, ordering freeze ≤ stop ≤ archive:

The pattern Dormice was built for — one permanent sandbox per agent:

tsCopy code
await client.acquireSandbox(`agent-${userId}`, {
  policy: { stopAfterSeconds: null },
});

It parks at frozen (~5 MiB resident) and wakes in ~50 ms — never a cold start; frozen processes suspend mid-flight and resume exactly where they were. Commands and file operations reset the idle clock; observation (listSandboxes, metrics) never wakes or warms anything. A background process does not keep its sandbox warm — a resident sandbox means "ready whenever the agent returns", not an unattended 24×7 workload.

Gotchas

• Keep the API token hexadecimal. The Python E2B SDK validates e2b_[0-9a-f]+ client-side; other characters fail before any request.
• Bring a patient HTTP client. execCommand sends response headers only when the command finishes — legally hours later. Node's undici ships a hidden ~5-minute header timeout; disable it (the native SDK already does) or long commands die at exactly 300 s with an error that looks like the server's fault.
• Sandboxes run untrusted code, contained. Everything runs as a non-root user (uid 1000) inside gVisor, with passwordless sudo for installing system packages (E2B's convention; sudo apt install works, but survives only until the next cold wake — persistent tooling belongs in a template or under /home/user). The stock image ships Ubuntu 24.04, Python 3.12, Node 24, git, ripgrep, and jq.

Learn more

Docs (served as /llms.txt, /llms-full.txt, and per-page .md on the project site; sources on GitHub): quickstart · lifecycle · E2B SDKs · HTTP API · files · resident agents