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_:

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

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:

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:

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.